DBG-01 · SEC. 02 Debugging & Evaluation

Root Cause Debugging Loop

Force one hypothesis at a time against real evidence, so the AI stops guess-and-check fixing.

FORMAT: loop
DIFFICULTY: intermediate
TIME: 10 min
TOOLS: claude-code
MODELS: any
COPIES: 0 so far

When to use this

A bug is reported but the AI jumps straight to a fix without reproducing it. You've seen this fail before: the fix doesn't stick because nobody confirmed the actual cause.

The pattern

Pastes as plain text

We have a bug.

Follow this loop and do not skip steps:

1. Reproduce the bug first. Write or run a test/command that fails in the
   exact way described. Record the command, environment, exit result, and
   relevant redacted failure evidence. If you cannot reproduce it, stop and
   tell me what you tried.
2. State exactly one hypothesis for the root cause, based only on the
   evidence you've seen so far (code, logs, output). Do not list multiple
   possible causes.
3. Find evidence that confirms or rejects that hypothesis before writing
   any fix. Read the relevant code, add a log line, or run a targeted
   check. Show me the evidence.
4. If the hypothesis is wrong, discard it and go back to step 2 with a new
   one. Do not carry forward assumptions from the rejected hypothesis.
5. Only once you have confirmed the root cause with evidence, propose the
   fix and explain why it addresses the confirmed cause, not just the
   symptom.
6. Re-run the original failing reproduction from step 1 and record the exact
   command, environment, exit result, and relevant redacted passing evidence.

Do not guess. Do not propose a fix before completing step 3.

If this conversation already contains the bug report, use it and start
now. If not, first ask me to describe the bug and how I see it, then
wait for my reply.

Real example output

Step 1: Reproduced locally with `npm test -- checkout.spec.ts`, exit 1; failing assertion: expected total 42.50, got 45.00.
Step 2: Hypothesis: tax is applied twice, once in `calculateTotal` and once in the checkout summary component.
Step 3: Read `calculateTotal` (src/lib/pricing.ts:44), it does not apply tax. Read `CheckoutSummary.tsx:88`, confirmed it adds tax on top of a total that already includes it upstream in `useCart.ts:120`. Evidence confirms hypothesis.
Step 5: Removed the duplicate tax addition in `CheckoutSummary.tsx:88`.
Step 6: Re-ran `npm test -- checkout.spec.ts` locally, exit 0; all 6 tests pass, total now 42.50.

Why it works

Forcing one hypothesis at a time with evidence stops the AI from pattern-matching a plausible-looking fix onto the wrong cause. Reproducing first means the "fix" gets checked against the same failure that started the loop, not a new assumption.

Related patterns

DBG-05Assumption Audit Before DebuggingList every assumption behind a bug theory and mark each confirmed, unconfirmed, or false.DBG-13One Variable at a TimeA standing rule: one change per run while debugging, predict before you edit, revert what didn't help.DBG-07Bug Postmortem From a FixTurn a fixed bug into a structured postmortem so the same class of bug doesn't ship again.