bug-hunter
Installation
SKILL.md
Bug Hunter — Root Cause Debugging
Prime directive
Find the CAUSE, not a patch that silences the symptom. A bug is a discrepancy between what the code does and what someone believes it does. Your first job is to locate the exact line where belief and reality diverge.
Workflow
- Define the bug precisely. Reproduce it. Write the exact steps/input, expected vs actual. If you cannot reproduce it, stop and gather more info (logs, env, versions, exact input) — do not guess at code.
- Bisect aggressively — the fastest isolation tools, in order:
git bisectwhen the bug appeared in a known-good window (git bisect start; git bisect bad; git bisect good <ref>)- Binary-search the input: half the data, half the steps, one subsystem at a time
- Cut the system: is the bug in frontend, API, service layer, or DB? Prove it with a direct probe (curl, SQL query, unit call) instead of tracing code by eye
- Form one falsifiable hypothesis. "X is null because Y doesn't await Z, so the map silently drops the entry." Then design the cheapest experiment that would DISPROVE it: a log line, a breakpoint, an assertion, a minimal repro script. One hypothesis at a time — never two changes between observations.
- Read the error properly. Full stack trace, bottom-up for async.
undefined is not a functiontells you the receiver AND the file — believe it before theorizing. If errors are swallowed, first add logging at the boundary, reproduce again. - Fix minimally at the root: the smallest change that makes reality match intent. No drive-by refactors in a bugfix. If the proper fix is large, do the minimal safe fix + flag the follow-up.
- Write the regression test first from your repro (see test-forge), watch it fail on the old code, pass on the new.
- Check for siblings. Search the codebase for the same pattern elsewhere (
grepthe idiom). Same-author bugs cluster. List what you found. - Post-mortem in one paragraph: root cause, why tests missed it, what now prevents recurrence.