| name | root-cause-debugging |
| description | Systematic debugging — reproduce, bisect, prove the cause with a falsifiable hypothesis, fix minimally, re-verify against the original repro. Use for any bug, test failure, regression, or flaky behavior, before proposing a fix — and whenever a first fix didn't work. |
Root-Cause Debugging
Weak debugging looks like: read the error → pattern-match to a familiar cause → apply a plausible fix → declare victory. Strong debugging proves the cause before touching the fix. Follow this sequence and do not skip stages.
Stage 1 — Reproduce before anything else
Get the failure happening on demand, in the smallest command you can run repeatedly (a single test, a curl, a node one-liner). If you cannot reproduce it, your job is to instrument until you can — not to fix blind.
Write down (mentally or in a scratch file) the exact reproduction command and the exact observed-vs-expected output. This is the acceptance test for your fix.
Stage 2 — Locate by bisection, not intuition
Find where reality diverges from expectation by cutting the search space in half repeatedly:
- Trace the data: pick one concrete value that ends up wrong and follow it backward from the symptom to where it was last correct.
- Log/inspect at the midpoint of the suspected path; then midpoint again.
- Use git:
git log --oneline -- <file>, git bisect, or diff against the last-known-good commit when it's a regression.
- Distrust the error site. The line that throws is where the bad state was noticed, rarely where it was created.
Stage 3 — State the cause as a falsifiable sentence
Before fixing, complete this sentence with specifics: "The failure happens because [specific code] does [specific wrong thing] when [specific condition]."
Then try to falsify it: if this were true, what ELSE would be broken? Check that. If the hypothesis predicts things that aren't happening, it's wrong — go back to stage 2. A hypothesis you haven't tried to break is a guess.
Stage 4 — Fix the cause, minimally
- Fix where the bad state is created, not where it's detected.
- Prefer the smallest diff that makes the falsifiable sentence false.
- If the real fix is large and you must ship a symptom-level guard, say so explicitly in your report — never present a mitigation as a root-cause fix.
Stage 5 — Verify with the original reproduction
Run the exact stage-1 reproduction. Then run the surrounding test suite to check for collateral damage. A fix verified only by "the code looks right now" is not verified.
When a fix attempt fails
Do not stack a second guess on the first. Revert your mental model to stage 3: the failed fix is evidence — it falsified your hypothesis. Ask what the failure of the fix tells you about where the real cause is.
Flaky / intermittent failures
Don't average over the noise. Find the varying input: timing (race), ordering (test pollution, map iteration), environment (env var, port, clock), or data (random seed). Run the reproduction in a loop (for i in $(seq 20); do ...; done) to measure the failure rate before and after the fix — "passed once" is not evidence for a flake fix.
