debug

# Skill: /debug # Systematic Bug Diagnosis --- ## PROTOCOL Bugs have two parts: the **symptom** (what you observe) and the **cause** (what's actually wrong). The protocol moves from symptom → cause → fix, one verified step at a time. ### Phase 1 — Reproduce **Goal:** Reliable, minimal reproduction before touching any code. 1. State the symptom precisely: what input, what output, what was expected. 2. Find the smallest input that triggers it. 3. Verify you can reproduce it consistently. 4. Is this a regression? `git log --oneline -20` — when did it last work? **If you can't reproduce it:** Stop. Gather more information. Unreproducible bugs are unsolvable. ### Phase 2 — Isolate **Goal:** Narrow the search space to the smallest possible area. 1. Identify the layers involved: UI → API → service → DB → external? 2. Test each boundary — where does correct input produce wrong output? 3. Binary-search the call stack: disable half, does the bug disappear? 4. Is it environment-specific? dev vs prod? one machine vs all? **Isolation heuristics:** - Works in tests, breaks live → check environment (config, secrets, timing) - Started after a deploy → `git bisect` - Intermittent → look for shared mutable state, races, time-dependent logic ### Phase 3 — Hypothesize State one falsifiable hypothesis before changing any code: ``` Hypothesis : [what I think is wrong] Evidence for: [what supports this] Against : [what doesn't fit] Test : [one action that confirms or refut...