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

Phase 1 — Root Cause

Collect evidence before forming a theory. The goal of this phase is a sentence of the form "X fails because Y, and here is the observation that shows Y."

• Read the full error and stack trace, not the first line. The frame that matters is often three deep.
• Reproduce deterministically. A bug you can't reproduce, you can't verify you fixed.
• Capture the actual state at the failure point. When console.log can't reach the state (closure variables, a paused async frame, the Electron main process, WebSocket server internals), reach for the node-inspect-debugger skill — real breakpoints and a scope-chain dump beat sprinkled logs.
• Distinguish symptom from cause. "Returns undefined" is a symptom; "the map key is built from a stale closure value" is a cause.

Success criterion: you can name the cause in one sentence, backed by an observation. If you can only say "I think it's the cache," you are not done with Phase 1.

Phase 2 — Pattern

A bug is rarely unique. Before fixing this instance, ask whether the same class of mistake exists elsewhere.

• Grep for the same call shape / the same missing guard.
• If one handler forgot to await, check its siblings.
• Note candidates; you are cataloguing, not fixing them all now.

Success criterion: you've searched for sibling instances and know whether the fix is one-site or systemic.

Phase 3 — Hypothesis

State a hypothesis that could be wrong — and how you'd know. A theory that can't be disproven isn't a diagnosis, it's a belief.

• Change one variable at a time. If you change three things and it works, you've learned nothing about which mattered — and added two new liabilities.
• Predict the outcome before you run: "If the cause is the stale key, forcing a fresh key makes the failure disappear; if it still fails, my theory is wrong."
• A failed prediction is a result, not a setback — it eliminates a branch.

Success criterion: you have a one-variable change and a falsifiable prediction.