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

  1. 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.
  2. Bisect aggressively — the fastest isolation tools, in order:
    • git bisect when 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
  3. 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.
  4. Read the error properly. Full stack trace, bottom-up for async. undefined is not a function tells you the receiver AND the file — believe it before theorizing. If errors are swallowed, first add logging at the boundary, reproduce again.
  5. 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.
  6. Write the regression test first from your repro (see test-forge), watch it fail on the old code, pass on the new.
  7. Check for siblings. Search the codebase for the same pattern elsewhere (grep the idiom). Same-author bugs cluster. List what you found.
  8. Post-mortem in one paragraph: root cause, why tests missed it, what now prevents recurrence.
Installs
48
GitHub Stars
6
First Seen
Aug 31, 2026