| name | debug |
| description | Systematic root-cause debugging — reproduce, isolate, fix at the source, prove the fix. Use when the user reports a bug, an error, a crash, flaky behavior, "this doesn't work", "why is this failing", or pastes a stack trace or failing test output. |
Debug
Find the root cause before touching code. A fix without a understood cause is a guess wearing a fix's clothes.
Step 1 — Reproduce
- Get a deterministic reproduction before anything else: failing test, curl command, or exact click path. If you can't trigger it, you can't prove you fixed it.
- Read the actual error verbatim — full message, full stack trace, not a paraphrase. The answer is often in the line the eye skips.
- Capture the reproduction as a failing automated test now when feasible. It becomes the regression test in Step 5 for free.
- Flaky bugs: run the repro in a loop (
go test -run X -count=100, vitest --retry=0 repeated) to establish a failure rate before changing anything.
Step 2 — Shrink the search space
Cheapest checks first:
- Recent changes:
git log --oneline -15 and git diff HEAD~5 on the touched area. Most bugs are days old, not years. git bisect when a known-good commit exists and the repro is scriptable.
- Boundaries: is the bad value born here or delivered here? Log/inspect at the boundary (request in, DB out, API response) to decide which side owns the bug.
- Binary search: cut the path in half — instrument the midpoint, determine which half is wrong, repeat. Never shotgun ten print statements at once; each probe should answer one question.
- Question one assumption per probe: "this config is loaded", "this branch runs", "this is the version deployed". Verify, don't assume — the bug lives in a false assumption.
Step 3 — Identify root cause
- Keep asking "why" past the first plausible answer. Symptom: nil deref. Cause: field unset. Root cause: constructor allows partial init. Fix the constructor.
- Before fixing a shared function, grep its callers. If the bug can bite them too, the fix belongs in the shared code path, not in the one caller from the bug report.
- State the root cause in one sentence. If you can't, you haven't found it — return to Step 2.
Step 4 — Fix
- Smallest change that removes the root cause. No drive-by refactors, no "while I'm here" — separate commits for that (see
refactor skill).
- If the real fix is large and something is bleeding in prod, a guard + TODO is acceptable — but say explicitly it's a mitigation, name the real fix, and don't call the bug closed.
Step 5 — Prove it
- The Step 1 reproduction now passes. The rest of the test suite still passes.
- Remove every temporary probe/print you added.
- Report: root cause (one sentence), the fix, how it's verified. If tests still fail, say so — never declare victory on partial evidence.
Per-stack probes
Read references/tools.md when you need stack-specific instrumentation: delve / go test -race, Node --inspect and vitest filtering, browser devtools for frontend state/hydration issues, SQL logging for query bugs.
