systematic-debugging

Systematic Debugging

Overview

A bug is a gap between what the code does and what you believe it does. Guessing at fixes closes the gap by accident, if at all — and each blind edit adds a new variable that hides the real cause. Systematic debugging is the discipline of gathering evidence until the cause is known, then changing exactly one thing.

The failure mode this skill prevents: reading a stack trace, forming an instant theory, editing code to match the theory, re-running, and repeating. That loop feels like progress and usually is not — it mutates the system faster than it explains it.

When to Use

• A test fails and the message doesn't immediately tell you why
• Behaviour differs between environments ("works locally, fails in CI", "works in dev mode, not production")
• A fix you already tried didn't work (you are now on attempt ≥ 2 — stop guessing)
• An intermittent / flaky failure you can't reproduce on demand
• A regression: something that worked now doesn't, and you don't know which change broke it

When NOT to use:

• The cause is already obvious and proven (typo, off-by-one you can see, wrong constant)
• You are building a new feature, not diagnosing existing behaviour
• The "bug" is actually a missing requirement — that's a spec conversation, not a debug session

The Four Phases

Each phase has a success criterion. Do not advance until it is met. Skipping ahead is the whole antipattern.

Phase 1  ROOT CAUSE      gather evidence ─▶ criterion: you can state the cause in one sentence
   │                                        with evidence, not a guess
   ▼
Phase 2  PATTERN         is this cause elsewhere? ─▶ criterion: you've searched for sibling
   │                                                 instances of the same class of bug
   ▼
Phase 3  HYPOTHESIS      change ONE variable ─▶ criterion: a prediction that, if wrong,
   │                                            disproves your theory (a real test)
   ▼
Phase 4  IMPLEMENTATION  fix + regression test ─▶ criterion: a test that fails before the fix
                                                  and passes after