Systematic Debugging

Iron Law

IF >= 3 FIXES TRIED, STOP AND QUESTION THE ARCHITECTURE

Phases

1. Reproduce

• Get the exact error message and stack trace
• Write a failing test if possible
• If you cannot reproduce it, you cannot fix it

2. Hypothesize

• Rank them by likelihood
• Explain the reasoning behind each
• Do NOT skip to fixing before hypothesizing

3. Investigate

• Binary search: narrow the problem space by halving (comment out half the code, does it still fail?)
• Trace: follow the execution path from input to failure point
• Instrument: add logging/assertions at key points to observe state

4. Fix

• Explain what the fix does and why it solves the root cause
• Do NOT fix symptoms — fix root causes
• If the fix touches more than 10 lines, question whether it's minimal

5. Verify

• It must pass
• The bug must no longer occur

6. Regression

• No new failures introduced
• If regressions appear, your fix changed behavior — investigate before committing

Red Flags — If You Catch Yourself Thinking:

Rules

• NEVER skip reproduction
• NEVER apply more than 3 fixes without stepping back and questioning the architecture
• ALWAYS verify the fix doesn't introduce regressions
• Document what you tried and what you learned in progress.txt