systematic-debugging

Systematic Debugging

When something is wrong, do not propose fixes from intuition. Work the problem.

The loop

1. Reproduce. Find the smallest sequence of steps that reliably triggers the bug. If you can't reproduce it, you can't fix it — keep trying or instrument the code to capture the next occurrence.

2. Isolate. Cut the reproduction down to the minimum. Strip unrelated state. Find the smallest possible failing case.

3. Hypothesize. State what you think is happening. ONE hypothesis at a time. Be specific: not "the parser is broken" but "the parser discards trailing whitespace before checking for the closing token."

4. Test the hypothesis. Add a print, attach a debugger, write a focused test, read the relevant code closely. Look for evidence that confirms or denies. Be honest — confirmation bias is the enemy.

5. If wrong, go back to step 3. Discard the hypothesis. Form a new one. Don't bend the evidence.

6. Once confirmed, fix. The fix should target the root cause, not the symptom.

7. Add a regression test that would have caught the bug. Confirm it fails before the fix and passes after.

Three failed fixes — stop and question the architecture

If you've tried three or more hypotheses and the bug persists, STOP iterating on fixes. The bug is probably not where you think it is. Step back and ask:

• Am I debugging the symptom in the wrong component?
• Is there hidden state (cache, retry, environment, race) that I haven't accounted for?
• Is the mental model I'm working from actually correct?

Re-read the relevant code with fresh eyes. Tell the user you've hit a wall, summarize the three failed hypotheses and what each ruled out, and ask whether the architecture itself needs to change before more fix attempts.

Anti-patterns

• "Maybe if I change X it'll fix it" — that's not debugging. Form a hypothesis or stop.
• Adding logging then declaring victory without evidence the bug is understood.
• Fixing symptoms (catch-and-ignore, retry loops) instead of causes.
• Closing the bug after one successful run — re-run the original reproduction to confirm.

Done

You're done debugging when:

• A regression test exists and passes.
• The original reproduction no longer triggers the bug.
• You can explain in one sentence what was wrong and why the fix addresses it.