debug-detective

# 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 ...