debug

When to use

• User pastes an error, stack trace, failing test, or describes incorrect behaviour.
• Something works in staging but fails in production (or vice versa).
• A commit or dependency upgrade introduced a regression; git bisect is the right tool.
• A flaky test needs diagnosis (not just a retry).

Do not use this skill to write new features, to review a PR, or to answer "how do I use library X" — those are separate skills.

Inputs

• Symptom description, with as much context as the user has: error message, stack trace, steps to reproduce, environment (OS, runtime version, recent deploys).
• Access to logs, metrics, or a reproducible environment if possible.

Outputs

• A short session report with six sections: Symptom, Reproduction, Isolation, Hypothesis, Verification, Fix + Regression test.
• A patch that fixes the root cause (not just the symptom).
• At least one new automated test that fails on the pre-fix code and passes on the post-fix code.

Tool dependencies

• Read, Grep, Glob, Edit for code.
• Bash for the test runner, git bisect, git log, and language-specific debuggers (pdb, node --inspect, dlv, lldb, rust-gdb).
• Optional: a log aggregator MCP, or a profiler when the bug is performance-shaped.

Procedure

1. Symptom: restate the bug in one sentence. Include the expected behaviour next to the observed behaviour. If these two sentences are not both concrete and observable, ask the user to make them so before continuing.
2. Reproduce locally. A bug you cannot reproduce you cannot fix with confidence. Steps:
   • Capture the exact input and environment.
   • Reduce to the smallest failing case: shrink the input, strip unrelated configuration, run with a single worker, drop from integration to unit scope if possible.
   • If the bug needs a specific wall-clock or RNG, fake them.
   • If it is race-conditiony, run the repro in a loop (while pytest -x; do :; done) for at least a minute or use a deterministic scheduler.
   • If it is environment-specific, document the minimal environment. Never skip this step with "I'll just trust the logs".
3. Isolate with binary search. If the bug appeared after some change, run git bisect:

   git bisect start
   git bisect bad HEAD
   git bisect good <last-known-good>
   git bisect run <script-that-exits-nonzero-on-bug>
   

   For data-shape bugs, bisect inputs instead of commits: halve the failing input until the minimum repro is obtained.
4. Hypothesise. Before editing any code, write down the hypothesis: "the bug is caused by X because Y, which implies the symptom Z". If you cannot finish that sentence, you do not understand the bug yet — go back to step 2.
5. Verify the hypothesis. Make a cheap observation that would distinguish the hypothesis from its competitors: add a log, set a breakpoint, run an assertion, query the DB. Confirm the hypothesis matches reality end-to-end — not "the symptom went away" but "the predicted intermediate state is present".
6. Fix the root cause, not the symptom. A patch that makes the failing test pass can still be a coincidence. Specifically:
   • If you added a null-check, explain why the value is null and whether upstream is the real fault.
   • If you added a retry, explain why the first attempt fails and whether retry is an acceptable policy.
   • If you added a try/except, explain what invariant was actually violated. Record the causal chain in the report.
7. Add a regression test. The test must fail on the pre-fix code and pass after. Invoke the test-writer skill to place and name it conventionally. If the bug was a race, the test must deterministically reproduce it (synchronised scheduler, controlled clock); a probabilistic test is unacceptable.
8. Verify the fix does not regress neighbours. Run the full test suite plus any integration/e2e gates. For performance bugs, run the relevant benchmark.
9. Write the report. Keep it short; link logs and commits rather than pasting them. Example format below.