User request: $ARGUMENTS

Systematic bug investigation and fix workflow. Follows: Understand → Hypothesize → Investigate → Fix → Verify.

Investigation log: /tmp/bugfix-{YYYYMMDD-HHMMSS}-{name-kebab-case}.md - external memory for findings.

Phase 1: Understand the Bug

1.1 Create Todo List

- [ ] Gather bug symptoms and context
- [ ] Form initial hypotheses
- [ ] (expand as investigation reveals new areas)
- [ ] Implement and verify fix

1.2 Create Investigation Log

Path: /tmp/bugfix-{YYYYMMDD-HHMMSS}-{name-kebab-case}.md

# Bug Investigation: {description}
Started: {timestamp}

## Symptoms
(populated below)

## Hypotheses
(populated in Phase 2)

## Investigation Log
(populated during investigation)

## Root Cause
(populated when identified)

## Fix Applied
(populated after fix)

1.3 Gather Symptoms

If $ARGUMENTS contains sufficient context (error message, steps to reproduce, expected vs actual behavior), extract and document in log.

Otherwise, ask user for missing information:

Bug Report Details Needed

To investigate effectively, please provide:

1. **What happened?** (Error message, unexpected behavior)
2. **What did you expect?** (Expected behavior)
3. **Steps to reproduce** (If known)
4. **When did it start?** (Recent change, always broken, intermittent)
5. **Environment** (Browser, OS, versions - if relevant)

Provide what you know - I can investigate the rest.

Document all symptoms in investigation log immediately.

1.4 Locate Relevant Code

Search codebase for:

• Files mentioned in error messages
• Functions/components referenced
• Recent changes (if "started after X" was mentioned)
• Related test files

Update log with located files.

Phase 2: Form Hypotheses

2.1 Generate Hypotheses

Based on symptoms and located code, form 2-4 hypotheses ranked by likelihood:

## Hypotheses

### H1: [Most likely] {Description}
- Evidence for: {what supports this}
- Evidence against: {what contradicts}
- Test: {how to verify/falsify}

### H2: {Description}
- Evidence for: {what supports}
- Evidence against: {what contradicts}
- Test: {how to verify/falsify}

### H3: [Least likely] {Description}
...

2.2 Update Todos

- [x] Gather bug symptoms and context
- [ ] Form initial hypotheses
- [ ] Investigate H1: {description}
- [ ] Investigate H2: {description}
- [ ] (expand as investigation reveals new areas)
- [ ] Implement and verify fix

Phase 3: Investigate

Investigation Loop

For each hypothesis (in likelihood order):

1. Mark todo in_progress
2. Read relevant code files fully
3. Trace execution paths
4. Look for conditions that match symptoms
5. Write findings immediately to investigation log
6. Update hypothesis status: CONFIRMED | REFUTED | NEEDS MORE DATA
7. If confirmed → proceed to Phase 4
8. If refuted → mark completed, investigate next hypothesis
9. If all refuted → expand hypotheses based on new learnings

3.1 Investigation Techniques

General techniques:

• Read error messages and stack traces carefully
• Check logs and debugging output
• Examine data flow and state changes
• Consider environmental factors (OS, versions, config)
• Review recent commits for related changes (git log --oneline -20)

3.2 Log Format

After each investigation step:

### {timestamp} - Investigating H{N}
**Files examined**: {list}
**Findings**: {what discovered}
**Status**: CONFIRMED | REFUTED | NEEDS MORE DATA
**Next**: {what to check next or "proceed to fix"}

3.3 Root Cause Identified

When root cause is found:

## Root Cause

**Hypothesis confirmed**: H{N}
**Location**: {file}:{line}
**Cause**: {clear explanation}
**Evidence**: {code showing the bug}

If no hypothesis was confirmed but investigation revealed the actual cause, document the unexpected finding and proceed.

Phase 4: Test-First (When Applicable)

Before fixing, create a test that reproduces the bug when practical:

4.1 Create Reproducing Test

- Find the most appropriate existing test file for the component
- Create a minimal, focused test that reproduces the bug
- Run the test to verify it fails as expected
- If test passes, refine until it properly reproduces the issue

Why test-first?

• Proves you understand the bug
• Provides automatic verification when fix is applied
• Prevents regression in the future
• Documents the bug behavior

Skip test-first when:

• Bug is in UI/visual layer without existing test infrastructure
• Environment-specific issue that can't be unit tested
• Urgent hotfix where manual verification is sufficient (note in log)

4.2 Document Test in Log

## Reproducing Test

**Test file**: {path}
**Test name**: {description}
**Status**: FAILS AS EXPECTED | SKIPPED (reason)

Phase 5: Fix

5.1 Plan the Fix

Before implementing, document:

## Planned Fix

**Approach**: {what will change}
**Files to modify**: {list}
**Risk assessment**: {potential side effects}
**Test strategy**: {how to verify}

5.2 Implement Fix

Apply the minimal fix:

• Change only what's necessary
• Follow existing code patterns
• Don't refactor unrelated code
• Add comments if the fix isn't obvious

5.3 Run Quality Gates

# TypeScript: tsc --noEmit
# Tests: npm test (or project-specific)
# Lint: npm run lint (or project-specific)

5.4 Handle Gate Failures

If gates fail after fix:

1. Analyze if failure is related to fix or pre-existing
2. If related: adjust fix, re-run gates (max 5 attempts)
3. If pre-existing: note in log, continue
4. If stuck after 5 attempts: escalate with findings

Phase 6: Verify

6.1 Run Reproducing Test

If test was created in Phase 4:

• Run the test that previously failed
• If it passes → fix is verified
• If it still fails → return to Phase 5 to adjust fix

Attempt to reproduce the original bug:

• If bug no longer reproduces → fix likely successful
• If bug still reproduces → fix incomplete, return to Phase 3

6.2 Manual Verification

If no reproducing test exists:

• Attempt to reproduce the original bug
• If bug no longer reproduces → fix likely successful
• If bug still reproduces → fix incomplete, return to Phase 3

6.3 Check for Regression

Verify the fix didn't break related functionality:

• Run related tests
• Check adjacent code paths
• Consider edge cases

6.4 Document Fix

Update investigation log:

## Fix Applied

**Files modified**: {list with changes}
**Verification**: {how verified}
**Gates**: PASS | FAIL (reason)

## Summary

**Bug**: {description}
**Root cause**: {explanation}
**Fix**: {what was changed}
**Status**: FIXED | PARTIALLY FIXED | ESCALATED

6.5 Report to User

## Bug Fix Complete

**Bug**: {description}
**Root cause**: {one sentence}
**Fix**: {what was changed}
**Files modified**: {list}
**Verification**: All gates pass, bug no longer reproduces

**Investigation log**: /tmp/bugfix-{...}.md

Edge Cases

Principles

• Write findings immediately — investigation log is external memory
• Test-first when possible — a reproducing test proves understanding
• One bug at a time — don't fix unrelated issues
• Minimal fix — change only what's necessary
• Verify thoroughly — ensure fix works and doesn't regress
• Escalate when stuck — don't spin indefinitely

Quality Standards

• Tests must be deterministic and reliable
• Fixes should be clean and maintainable
• No introduction of new bugs or regressions
• Clear comments explaining non-obvious fixes
• Follow project coding standards and patterns