Root-Cause Debugging

The defining failure of mediocre debugging is pattern-matching: the error looks like a known problem, so a known fix gets applied, the symptom moves, and the actual bug ships. Everything below is designed to force contact with the real mechanism.

The protocol

1. Reproduce first

A bug you can't reproduce is a bug you can't prove you fixed. Get the failure into the smallest, fastest loop available — one test, one command, one curl. Every minute spent shrinking the repro pays back in every iteration after it. If it's genuinely irreproducible (race, environment), say so explicitly and shift to instrumenting for the next occurrence rather than guessing.

2. Read the error as evidence, not noise

The exact message, the exact line, the full stack, the first error rather than the loudest one. A remarkable share of "mysterious" bugs are answered verbatim in text that nobody actually read. If the error references a file or value, go look at that file and that value — not your mental model of them.

3. Localize before theorizing

Shrink the search space mechanically before reasoning about causes:

• Regression? git bisect — or just diff against the last-known-good commit.
• State corruption? Binary-search with targeted logging or asserts at boundaries.
• Data-dependent? Shrink the input until the failure disappears; the last-removed piece is a coordinate of the bug.

One targeted print at a component boundary beats ten minutes of theorizing. Instrument; don't speculate.

4. Hypothesize plurally, test discriminately

Before testing anything, write down two or three candidate mechanisms. The first hypothesis anchors you; deliberately generating rivals is the antidote. Then design the experiment that distinguishes between them — not the one that confirms your favorite. "If it's A, the log shows X; if it's B, X is absent" is worth more than any amount of confidence.

5. Fix the mechanism, not the symptom

Before applying a fix, say the causal sentence: "X happens because Y, so changing Z prevents it." If you can't say it, you have a symptom patch, not a fix. Classic tells that you're patching symptoms:

• A null/undefined check added without knowing why the value was ever null
• A sleep/retry that makes a race "go away"
• Reordering operations because it "seems to help"
• Catching and swallowing the exception

Each of these leaves the bug alive and now hidden.

6. The stuck circuit breaker

After two failed fixes, stop editing code. You are in a local minimum, and the third variation of the same idea will not escape it. Instead:

1. Write down (actually write — scratchpad or state file) two lists: facts you have observed, and assumptions you haven't verified.
2. For each failed fix, identify which assumption it silently relied on.
3. Verify assumptions in order of shakiness — usually one of them is false.
4. Widen the frame: right file, but wrong process? Stale build or cache? Is the test wrong rather than the code? Environment differs from what you think? Are you even running the code you're editing? (Add a deliberate syntax error or print to prove the edit is live — the "tracer bullet" check.)
5. Re-read the failing path from its entry point as if you'd never seen the code.

Being stuck is information: it means the world differs from your model somewhere upstream of where you're looking.

7. After the fix

• Re-run the original reproduction — the actual one, not a proxy.
• Run the surrounding test suite; fixes regress neighbors.
• Add a regression test and confirm it fails without the fix — a test that passes either way is decoration. If you catch yourself arguing that the existing suite already covers it ("the failing order reproduces it"), add a focused, order-independent test anyway: incidental coverage is how the bug survived until now, and the next refactor of the suite will quietly delete it.
• Ask: where else does this same pattern exist? Bugs come in families; the sibling copy-pasted three files away is cheaper to fix now than after its own incident. Don't just wonder — grep for the literal idiom you just fixed (the method call, the assignment shape, the API misuse) and check every hit. A dormant sibling has no failing test yet; that's exactly why only this search will find it.

Scope note

If the user only described the problem or asked why it happens, the deliverable is the diagnosis — mechanism, evidence, and proposed fix. Apply the fix when they ask.