Systematic Debugging
Iron law: no fixes without root-cause investigation. Fixing symptoms is failure.
The simpler the bug looks, the more urgent the situation, the more this process matters — systematic debugging is faster than guess-and-patch thrashing.
The four phases (complete each before the next)
Phase 1: Root cause investigation
- Read error messages to the end — full stack trace, line numbers, error codes. The answer is often already there
- Reproduce consistently — if you can't reproduce, gather more data instead of guessing
- Check recent changes — git diff, recent commits, dependency/config/environment differences
- Multi-component systems: instrument first — log what enters/exits each component boundary, run once to see WHERE it breaks, then investigate that layer
- Trace data flow backwards — follow the bad value up the call stack to its origin; fix at the source, never at the symptom site
Phase 2: Pattern analysis
- Find similar working code in the same codebase and compare
- If there is a reference implementation, read it completely (no skimming)
- List every difference between working and broken — no "that can't matter" assumptions
Phase 3: Hypothesis and test
- One hypothesis, stated clearly: "I think X is the cause because Y"
- Test with the smallest possible change — one variable at a time
- If it fails, form a new hypothesis. Never stack fixes on top of fixes
- If you don't understand something, say "I don't understand X". No pretending
Phase 4: Implementation
- Write the failing test case first (minimal reproduction) before fixing
- One fix for the identified root cause — no "while I'm here" refactoring
- Verify: test passes? nothing else broken?
The 3-failures rule
If 3+ fix attempts have failed, question the architecture. When every fix reveals a new problem somewhere else, the structure is wrong, not the hypothesis. Do not attempt fix #4 — discuss the architecture with the user first.
Red flags (any of these thoughts → STOP, back to Phase 1)
- "Quick fix now, investigate later"
- "Just try changing X and see"
- "Change several things at once and run the tests"
- "Skip the test, I'll verify manually"
- "I don't fully understand it, but this might work"
- Listing solutions before tracing the data flow
1---2name: systematic-debugging-23description: Use on any bug, test failure, or unexpected behavior, before proposing fixes. No fixes without root-cause investigation4---56# Systematic Debugging78**Iron law: no fixes without root-cause investigation. Fixing symptoms is failure.**910The simpler the bug looks, the more urgent the situation, the more this process matters — systematic debugging is faster than guess-and-patch thrashing.1112## The four phases (complete each before the next)1314### Phase 1: Root cause investigation15- **Read error messages to the end** — full stack trace, line numbers, error codes. The answer is often already there16- **Reproduce consistently** — if you can't reproduce, gather more data instead of guessing17- **Check recent changes** — git diff, recent commits, dependency/config/environment differences18- **Multi-component systems: instrument first** — log what enters/exits each component boundary, run once to see WHERE it breaks, then investigate that layer19- **Trace data flow backwards** — follow the bad value up the call stack to its origin; fix at the source, never at the symptom site2021### Phase 2: Pattern analysis22- Find similar working code in the same codebase and compare23- If there is a reference implementation, read it **completely** (no skimming)24- List every difference between working and broken — no "that can't matter" assumptions2526### Phase 3: Hypothesis and test27- One hypothesis, stated clearly: "I think X is the cause because Y"28- Test with the **smallest possible change** — one variable at a time29- If it fails, form a new hypothesis. Never stack fixes on top of fixes30- If you don't understand something, say "I don't understand X". No pretending3132### Phase 4: Implementation33- **Write the failing test case first** (minimal reproduction) before fixing34- One fix for the identified root cause — no "while I'm here" refactoring35- Verify: test passes? nothing else broken?3637## The 3-failures rule38If 3+ fix attempts have failed, **question the architecture.** When every fix reveals a new problem somewhere else, the structure is wrong, not the hypothesis. Do not attempt fix #4 — discuss the architecture with the user first.3940## Red flags (any of these thoughts → STOP, back to Phase 1)41- "Quick fix now, investigate later"42- "Just try changing X and see"43- "Change several things at once and run the tests"44- "Skip the test, I'll verify manually"45- "I don't fully understand it, but this might work"46- Listing solutions before tracing the data flow
jh941213