Systematic Debugging skill for Claude Code

A bug is fixed when you can explain the mechanism, a test that failed now passes, and nothing else changed behavior. A symptom that disappears after an unexplained edit is not fixed — it is hidden.

Ground rules

• Do not edit code until you can reproduce the failure or have a written reason why reproduction is impossible.
• Change one variable per experiment. Revert experiments that did not confirm anything.
• Read the actual error. The first line of the trace and the deepest frame inside the project’s own code matter more than the framework frames between them.
• Treat every “this can’t be the problem” as a hypothesis to test, not a fact.
• After two failed fix attempts, stop patching and return to step 2 with fresh evidence.

Workflow

Copy this checklist into your working notes and tick items as you go:

- [ ] 1. Capture the exact symptom
- [ ] 2. Reproduce reliably (ideally as a failing test)
- [ ] 3. Narrow the search space
- [ ] 4. Form ranked hypotheses
- [ ] 5. Test hypotheses with minimal experiments
- [ ] 6. Fix the cause, not the symptom
- [ ] 7. Verify and guard against regression
- [ ] 8. Report the root cause

1. Capture the exact symptom

Record before touching anything:

• Expected vs. actual behavior, in one sentence each.
• The full error text and stack trace (not a paraphrase).
• Environment: runtime and dependency versions, OS, config/env vars that differ from the working case, data involved.
• When it started: last known good commit, deploy, or dependency bump.

Useful commands:

git log --oneline -15                 # what changed recently
git diff <last-good>..HEAD --stat     # scope of change since it worked
node -v; python3 --version            # runtime versions actually in use

2. Reproduce reliably

Prefer the smallest reproduction in this order:

1. An automated failing test in the project’s existing test framework.
2. A single command or script that fails deterministically.
3. A documented sequence of manual steps.

If the failure is intermittent, loop it to measure the rate before and after any fix:

for i in $(seq 1 50); do npm test -- -t "checkout total" >/dev/null 2>&1 || echo "fail $i"; done

Intermittent failures are usually ordering, timing, shared state, or environment. For those, read references/flaky-and-heisenbugs.md.

3. Narrow the search space

Pick the cheapest technique that cuts the space in half:

Situation	Technique
It worked at a known commit	git bisect (automate with git bisect run <test-cmd>)
Large input triggers it	Delta-reduce the input until removing anything makes it pass
Long pipeline / many layers	Check the data at the midpoint; recurse into the bad half
Works in env A, fails in B	Diff the environments: versions, env vars, config, data, locale, timezone
Exception far from cause	Find where the bad value was first created, not where it was used

git bisect start
git bisect bad HEAD
git bisect good <last-good-sha>
git bisect run npm test -- -t "checkout total"
git bisect reset

4. Form ranked hypotheses

Write two to four candidate explanations. For each, note what evidence would confirm or rule it out. Rank by likelihood multiplied by cheapness to test. Common root-cause families to check against:

• Wrong assumption about input shape: null/undefined, empty collection, unicode, timezone, numeric precision, string vs. number.
• State: stale cache, mutation of shared objects, missing reset between tests, global singletons.
• Ordering and timing: unawaited promise, race between writers, event fired before listener attached, retries applied twice.
• Boundaries: off-by-one, inclusive vs. exclusive ranges, pagination edges, limits.
• Integration drift: dependency upgrade, API contract change, schema migration not run, feature flag state.
• Configuration: wrong env file loaded, precedence of config sources, missing secret.

5. Test hypotheses with minimal experiments

• Add targeted logging or assertions at the boundary that distinguishes hypotheses. Log values and types: console.log({ total, type: typeof total }).
• Use a debugger or breakpoint() / debugger; when inspecting many variables.
• Prefer experiments that can disprove a hypothesis outright.
• Write down each result. Remove temporary logging before finishing.

6. Fix the cause, not the symptom

• Fix where the wrong value or behavior originates.
• Red flags that you are patching a symptom: adding a try/catch that swallows the error, a null check without knowing why the value is null, a sleep or retry to hide a race, special-casing the exact failing input.
• Keep the fix minimal. Do not bundle refactors with a bug fix; propose them separately.
• Search for the same pattern elsewhere: grep -rn "<pattern>" src/ — sibling bugs are common.

7. Verify and guard against regression

1. The reproduction from step 2 now passes.
2. Add or keep a regression test that fails without the fix. Confirm by temporarily reverting the fix and watching the test fail.
3. Run the full relevant test suite, plus lint and type checks.
4. For intermittent bugs, rerun the loop from step 2 and compare failure rates.

8. Report the root cause

End with a short note in this shape:

**Symptom:** Checkout total showed NaN for carts with a discounted bundle.
**Root cause:** `applyDiscount()` received the price as a string from the CSV import
and `"19.99" * 1` worked but `"19.99" + 0.5` concatenated. Introduced in a1b2c3d.
**Fix:** Parse prices to integer cents at the import boundary (src/import/csv.ts:42).
**Verification:** New test `bundle discount totals` fails before, passes after;
full suite green.
**Follow-ups:** Two other importers use the same pattern (listed in PR).

When you cannot reproduce

• Ask for (or gather) logs with timestamps, request IDs, exact versions, and input data.
• Add structured diagnostics at suspected boundaries behind a flag, ship them, and wait for the next occurrence rather than guessing at a fix.
• State plainly that the fix is speculative if you must ship one, and say what evidence would confirm it.