Claude Code Skill
Bug Debugger
Use when something is broken, a test fails, an error or stack trace appears, behavior is wrong or intermittent, a regression appeared after a change, or a fix attempt did not work — any language or framework.
Install
npx skills add WST2002/claude-code-skills --skill bug-debuggerOr copy skills/bug-debugger into ~/.claude/skills/.
Overview
Find the root cause before changing code. Reproduce, narrow down with evidence, fix the cause, and prove the fix with a test that failed before and passes after. Guess-and-patch loops waste more time than they save.
Method
- Reproduce. Get the exact command, input or steps that show the bug. Write it down. If it is intermittent, find the condition that makes it frequent (load, timing, data, order).
- Read the evidence fully. The whole error message and stack trace, the first error in the logs (not the last), the failing assertion's expected vs actual.
- Check what changed.
git log -p --since=<date> -- <path>, recent dependency updates, config or environment differences. For a known good commit,git bisect run <test command>. - Form one hypothesis that explains all the evidence. State it in one sentence.
- Test the hypothesis cheaply: a log line, a breakpoint, a minimal script, or a failing unit test. Confirm or discard it. Never change two things at once.
- Trace to the root. Ask why the bad value or state exists, and keep asking until you reach the place where it was first wrong. Fix there, not where it crashed.
- Write a failing test that reproduces the bug, then fix, then watch the test pass and run the full suite.
- Remove debugging code (temporary logs, prints, breakpoints).
Output contract
Bug: <one line>
Reproduce: <command or steps>
Root cause: <what was wrong, file:line, and why it happened>
Fix: <the change>
Proof: <test name> failed before, passes after; full suite: <result>
If the root cause is not found yet, report what was ruled out and the next experiment instead of guessing a fix.
Quick reference
| Symptom | Look first at |
|---|---|
| Works locally, fails in CI or prod | Environment variables, versions, time zone, file paths, case sensitivity |
| Intermittent | Shared state, ordering, async without await, timeouts, caching |
| Wrong value | Where the value is first computed or transformed, not where it is displayed |
| Started after an update | Changelog of the updated dependency; lockfile diff |
undefined / null errors |
The caller that passed it, and the data source |
| Slow or hanging | Unbounded loops, missing timeouts, locks, N+1 queries |
Common mistakes
- Changing code before reproducing the bug.
- Reading only the last line of a stack trace.
- Fixing the symptom (adding a null check) while the bad data still comes from upstream.
- Trying a third fix after two failed ones without new evidence. Step back and re-read the evidence.
- Declaring it fixed without a test that failed before the fix.