/debug - Systematic Debugging

Investigate and fix the bug using 4-phase methodology.

Target: $ARGUMENTS

The 4 Phases

Phase 1      Phase 2       Phase 3        Phase 4
┌────────┐  ┌─────────┐  ┌───────────┐  ┌───────────┐
│ GATHER │─►│ ANALYZE │─►│ FORMULATE │─►│ IMPLEMENT │
│Evidence│  │ Patterns│  │ Hypothesis│  │  & Prove  │
└────────┘  └─────────┘  └───────────┘  └───────────┘

Workflow

Phase 1: GATHER EVIDENCE

1. Read the error completely:

   • Full error message
   • Stack trace
   • File and line numbers

2. Reproduce the bug:

   • Document exact steps
   • Confirm reproducible

3. Check recent changes:

   git log --oneline -10
   git diff HEAD~3

4. Search for related code:

   grep -r "error message" .

Output:

## Evidence

Error: [full message]
Location: [file:line]
Stack trace: [trace]

Reproduction:
1. [step]
2. [step]
3. Error occurs

Recent changes:
- [commit]: [relevant change]

BLOCKED until evidence collected.

Phase 2: ANALYZE PATTERNS

1. Trace execution path:

   • Entry point → Error location
   • Data flow through system

2. Compare with working code:

   • Find similar code that works
   • Identify differences

3. Identify patterns:

   • Consistent or intermittent?
   • Data-dependent?
   • Timing-dependent?

Output:

## Analysis

Execution: [entry] → [fn1] → [fn2] → [error]

Working vs Broken:
| Aspect | Working | Broken |
|--------|---------|--------|
| [X]    | [value] | [value]|

Patterns:
- [pattern 1]
- [pattern 2]

BLOCKED until patterns identified.

Phase 3: FORMULATE HYPOTHESIS

1. Generate hypotheses:

   • Multiple, not just one
   • Based on evidence

2. Rank by probability:

   • Which fits all evidence?
   • Simplest explanation?

3. Design tests:

   • How to prove/disprove each?

Output:

## Hypotheses

H1: [most likely] (80%)
  Evidence for: [...]
  Test: [how to verify]

H2: [second option] (15%)
  Test: [how to verify]

BLOCKED until hypotheses formulated.

Phase 4: IMPLEMENT & PROVE

1. Test primary hypothesis:

   • Execute minimal test
   • Capture output

2. If confirmed:

   • Write test that reproduces bug
   • Implement fix
   • Verify test passes

3. If rejected:

   • Test next hypothesis

4. Create checkpoint:

   git add -A && git commit -m "fix: [description]"
   git tag checkpoint/bugfix-[name]

Output:

## Resolution

Hypothesis: H1 - CONFIRMED ✓

Root Cause:
[Clear explanation]

Fix:
```diff
- [old code]
+ [new code]

Verification:

• Reproduction test: PASS ✓
• Existing tests: PASS ✓

## Three-Strike Rule

After 3 failed hypotheses:

⚠️ THREE STRIKES Re-evaluating understanding of the system. Looking for deeper architectural issues.

## Output

──── /debug ──── Bug: [description]

Phase 1: Evidence gathered ✓ Phase 2: Patterns identified ✓ Phase 3: Hypotheses formulated ✓ Phase 4: Fix implemented ✓

──── Debug Summary ──── Root cause: [explanation] Fix: [what changed] Checkpoint: checkpoint/bugfix-[name] Confidence: HIGH

## Anti-Rationalization

| Excuse | Reality |
|--------|---------|
| "I know the fix already" | You have a hypothesis, not a fix. Follow the phases. |
| "It's obviously this line" | Obvious fixes that skip investigation create new bugs. |
| "I'll just try this quickly" | Quick fixes without understanding cause regressions. |
| "Too slow to gather evidence" | Debugging without evidence takes 3x longer. |
| "The error message tells me everything" | Error messages are symptoms, not root causes. |

## Rules

1. **Never guess** - Evidence first
2. **Never fix without understanding** - Know the root cause
3. **Never skip phases** - Each prevents blind spots
4. **Always checkpoint** - Fixes must be reversible