Debug

When to Use

Invoke with /debug when:

• A bug has been reported or observed and needs systematic investigation
• A test is failing and the cause isn't obvious
• Something "just stopped working" and you need to find out why
• Previous fix attempts haven't resolved the issue
• You want to ensure the fix includes a regression test

Process

Phase 1: Reproduce

Before investigating, establish a reliable reproduction:

1. Get the symptoms — exact error message, stack trace, unexpected behavior
2. Get the trigger — what action causes the bug? What input?
3. Reproduce locally — can you make it happen on demand?
4. Identify consistency — does it always happen, or is it intermittent?

If you cannot reproduce the bug, do NOT guess at fixes. Instead, add logging/instrumentation to gather more data.

Phase 2: Hypothesize

Form hypotheses based on evidence, not intuition:

1. Read the error — what does the error message actually say?
2. Read the stack trace — where exactly does it fail?
3. Check recent changes — git log --since='3 days ago' — did something change?
4. Form 2-3 hypotheses — rank by likelihood

markdown
1### Hypotheses
21. [Most likely] — DB query returns null when user has no orders → NPE on line 45
32. [Possible] — Race condition between auth check and data fetch
43. [Less likely] — Timezone mismatch in date comparison

Phase 3: Investigate

Test each hypothesis systematically:

1. Start with the most likely hypothesis
2. Gather evidence — read the relevant code, check logs, add temporary logging
3. Narrow the scope — binary search: which layer? which function? which line?
4. Confirm or reject — does the evidence support this hypothesis?
5. Move to next hypothesis if rejected

Rules:

• Do NOT fix anything yet — investigation only
• Do NOT change code to "see if this helps"
• Every investigation step must produce evidence
• If you're guessing, you don't understand the bug yet

Phase 4: Root Cause

Document the confirmed root cause:

markdown
1### Root Cause
2**What**: [one sentence description]
3**Where**: [file:line]
4**Why**: [why does this code behave this way?]
5**When**: [under what conditions does this trigger?]
6**Evidence**: [how we confirmed this is the cause]

The root cause must explain ALL observed symptoms. If it doesn't, keep investigating.

Phase 5: Fix

Only after root cause is confirmed:

1. Design the fix — what's the minimal change that addresses the root cause?
2. Check for related issues — does this bug exist elsewhere? (same pattern in other files)
3. Implement the fix — one focused change
4. Verify the fix — reproduce the original bug → confirm it's gone
5. Check for regressions — run the full test suite

Rules:

• One fix per commit
• Fix the root cause, not the symptom
• Don't refactor surrounding code in the same commit
• If the fix is complex, explain why in the commit message

Phase 6: Regression Test

Write a test that:

1. Fails without the fix — reproduces the exact bug scenario
2. Passes with the fix — confirms the fix works
3. Tests the edge case — not just the happy path
4. Is named descriptively — describes the bug scenario, not the fix

text
1test("returns empty array when user has no orders instead of throwing NPE")

Output Format

markdown
1# Debug Report
2
3## Bug
4**Symptom**: [what the user sees]
5**Trigger**: [what action causes it]
6**Reproducible**: Yes/No/Intermittent
7
8## Investigation
9### Hypothesis 1: [description]
10- Evidence: [what we checked]
11- Result: Confirmed / Rejected
12
13### Hypothesis 2: [description]
14- Evidence: [what we checked]
15- Result: Confirmed / Rejected
16
17## Root Cause
18**What**: [description]
19**Where**: file:line
20**Why**: [explanation]
21**Evidence**: [how we confirmed]
22
23## Fix
24**Change**: [description of the fix]
25**Files**: [modified files]
26**Commit**: [commit hash]
27
28## Regression Test
29**Test**: [test name and location]
30**Verifies**: [what the test checks]
31
32## Related Issues
33- [Other places this pattern exists, if any]

Notes

• The #1 rule: no fix without confirmed root cause — guessing leads to patches that mask bugs
• Evidence-before-fix is non-negotiable — if you can't explain why the fix works, you don't understand the bug
• Intermittent bugs need more logging, not more guessing — add instrumentation first
• If the bug is in a dependency, document the workaround and file an upstream issue
• Each debug session should improve the codebase's debuggability (better error messages, logging, assertions)