Systematic Debugging
The Rule
code
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
Four Phases
Phase 1: Investigate
- •Read error messages completely - They often contain the solution
- •Reproduce consistently - Can you trigger it reliably?
- •Check recent changes -
git diff, what changed? - •Trace data flow - Where does the bad value come from?
Phase 2: Find Pattern
- •Find working similar code in codebase
- •Compare working vs broken
- •List every difference
Phase 3: Hypothesis
- •Form ONE hypothesis: "I think X because Y"
- •Make smallest possible change to test it
- •If wrong, form NEW hypothesis (don't pile fixes)
Phase 4: Fix
- •Write failing test that reproduces bug
- •Implement single fix for root cause
- •Verify test passes
- •Verify no other tests broke
Red Flags
If thinking:
- •"Quick fix, investigate later" - STOP
- •"Just try changing X" - STOP
- •"I don't understand but this might work" - STOP
Return to Phase 1.
3+ Fixes Failed?
If you've tried 3+ fixes without success:
- •STOP attempting more fixes
- •Question the architecture
- •Ask your orchestrator for guidance
Quick Reference
| Phase | Do | Confirm |
|---|---|---|
| Investigate | Read errors, reproduce, check changes | Understand WHAT and WHY |
| Pattern | Find working example, compare | Know the difference |
| Hypothesis | Single theory, minimal test | Confirmed or rejected |
| Fix | Test first, single fix, verify | Bug gone, tests pass |