debug-detectivelisted

Systematically root-causes software bugs using a reproduce → isolate → hypothesize → bisect → verify methodology, replacing guess-and-check debugging with a disciplined, evidence-driven investigation. Use this skill when a user reports a bug, a test is failing intermittently or consistently, behavior differs between environments, a regression appeared after a change, something "used to work" and now doesn't, an error/stack trace needs root-causing, or when asked to "debug", "find the root cause", "figure out why X happens", or "track down" a defect. Triggers include crashes, wrong output, flaky tests, hangs/deadlocks, memory leaks, performance regressions, heisenbugs, and works-on-my-machine problems.
JayRHa/AgentSkills · ★ 4 · AI & Automation · score 72

Install: claude install-skill JayRHa/AgentSkills

# Debug Detective ## Overview Debugging fails when it becomes random poking — changing lines, re-running, hoping. This skill enforces a **scientific, evidence-first** process: you never change code to "see what happens" until you have a falsifiable hypothesis backed by an observation. The goal is to find the *root cause*, not to make the symptom disappear. Keywords: debug, root cause, bug, regression, crash, stack trace, flaky test, intermittent, heisenbug, deadlock, memory leak, race condition, bisect, repro, reproduce, isolate, hypothesis, works on my machine. Core principle: **A bug you cannot reproduce is a bug you cannot confirm fixed.** Spend your effort earning a reliable reproduction first; everything else gets faster after that. ## Workflow Follow these phases in order. Do not skip ahead — a fix found by skipping is usually a coincidence, not a cure. ### 1. Capture & Reproduce - Collect the exact symptom: error message, stack trace, wrong vs. expected output, exit code, screenshot, logs. - Record the environment: OS, runtime/language version, dependency versions, config, env vars, data, concurrency, time/locale. - Build a **minimal reliable reproduction** — the smallest command/input that triggers the bug. Note how often it fails (100%? 1 in 20?). - If it is intermittent, quantify the rate and try to raise it (loop it, add load, shrink timeouts) before proceeding. See `references/intermittent-bugs.md`. - **Gate:** Do not continue until you can trigger the bug