Debug

Systematic Debugging

Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.

Random fixes waste time and mask underlying issues. If you haven't traced the bug to its origin, you don't understand it well enough to fix it.

When to Use This Skill

• A test is failing and the cause isn't immediately obvious
• A bug report describes unexpected behavior
• Something "used to work" and now doesn't
• An error message is confusing or misleading
• You've already tried one fix and it didn't work

Phase 1: Root Cause Investigation

Goal: Understand what's actually happening before proposing any fix.

1. Read error messages completely — including stack traces, line numbers, and surrounding context. Don't skim. The answer is often in the error message itself.

2. Reproduce consistently — if you can't reproduce it, you can't verify a fix. Document the exact reproduction steps.

3. Check recent changes — what changed since it last worked?

   git log --oneline -15
   git diff HEAD~5..HEAD -- <affected-files>
   

4. Trace the data flow — start from the error and work backward. At each component boundary, log what enters and what exits:

   • What data enters the failing function?
   • What data does it produce?
   • Where does the input come from?
   • Is the input what you expected?

5. Identify affected code paths — map which files, functions, and modules are involved. Read them fully — don't skim.

Phase 1 output: A clear statement of what is happening vs. what should happen, with evidence.

Phase 2: Pattern Analysis

Goal: Find working analogues to understand how the system is supposed to behave.

1. Find similar working code — search for functions, patterns, or flows that do something analogous and work correctly.

2. Compare implementations completely — don't just spot-check. Enumerate ALL differences between working and broken:

   • Different function signatures?
   • Different error handling?
   • Different data transformations?
   • Different initialization order?

3. Check for recurring patterns — has this type of bug happened before? Search git history:

   git log --all --oneline --grep="<error-keyword>"
   

4. Understand dependencies — map what the broken code depends on. Has any dependency changed version, API, or behavior?

Phase 2 output: Ranked list of hypotheses, most likely first, with evidence for each.

Phase 3: Hypothesis Testing

Goal: Systematically verify or eliminate each hypothesis. Scientific method — one variable at a time.

1. State your hypothesis explicitly: "I think X is happening because Y."

2. Design a minimal test for each hypothesis — change exactly ONE thing and observe the result.

3. Execute and record:

   • Hypothesis: [what you think is wrong]
   • Test: [what you changed]
   • Expected result: [what should happen if hypothesis is correct]
   • Actual result: [what actually happened]
   • Conclusion: [confirmed / eliminated / needs more data]

4. Never make compound changes — if you change two things and it works, you don't know which one fixed it. If you change two things and it doesn't work, you don't know if one of them was right.

5. Maximum 3 hypotheses before escalation — if your third hypothesis fails, STOP. You are likely missing something fundamental. Proceed to the Escalation Protocol.

Phase 3 output: Confirmed root cause with evidence, or escalation trigger.

Phase 4: Implementation

Goal: Fix the confirmed root cause with a regression test.

1. Write a failing test first that reproduces the exact bug. The test must:

   • Fail before the fix (proving it catches the bug)
   • Pass after the fix (proving the fix works)

2. Implement a single, targeted fix — address only the confirmed root cause. Do not "fix other things while you're in there."

3. Verify the fix:

   # Run the regression test
   npx vitest run <test-file> -- --reporter=verbose
   
   # Run the full suite to check for side effects
   npx vitest run
   

4. Verify no other tests broke — a fix that breaks something else isn't a fix.

Phase 4 output: Passing regression test + clean full suite.

Escalation Protocol

Trigger: 3 consecutive failed fix attempts OR 3 eliminated hypotheses without a confirmed root cause.

When triggered:

1. STOP immediately. Do not try a 4th fix.

2. Present findings to the user:

   ESCALATION: Root cause not confirmed after 3 attempts.
   
   What I investigated:
   - Hypothesis 1: [X] — Result: [eliminated because Y]
   - Hypothesis 2: [X] — Result: [eliminated because Y]
   - Hypothesis 3: [X] — Result: [eliminated because Y]
   
   What I know:
   - [fact 1]
   - [fact 2]
   
   What I suspect but cannot confirm:
   - [suspicion]
   
   Recommended next step:
   - [suggestion — e.g., "review the architecture of module X",
     "add instrumentation at boundary Y", "pair on this"]
   

3. Question architectural assumptions — if each fix reveals new problems in different places, the issue may be architectural, not a fixable bug. Say so explicitly.

Red Flags

These phrases in your own thinking should trigger an immediate pause and return to Phase 1:

Anti-Rationalization Table

Process Summary

Phase 1: Root Cause Investigation
  → What is actually happening? (evidence, not assumptions)

Phase 2: Pattern Analysis
  → What should be happening? (working analogues, comparisons)

Phase 3: Hypothesis Testing
  → Why is it happening? (one variable at a time, max 3 attempts)

Phase 4: Implementation
  → Fix it with proof. (regression test + targeted fix)

Escalation: 3 strikes → STOP → present findings → question architecture

Debug target: $ARGUMENTS

Resources

• Official Documentation