debugginglisted

# Debugging ## Iron Law `NO FIX WITHOUT ROOT-CAUSE EVIDENCE.` ## When to Use - Investigating defects, flakes, timing-sensitive bugs, regressions, production incidents, unclear failures, or "stuck" debugging sessions. ## When NOT to Use - Planned refactors with no failing behavior; use `refactoring`. - Performance investigation where the symptom is slowness; use `performance`. - Git-history regression search mechanics; pair with `git-workflow`. ## Core Ideas 1. Reproduce before fixing. Change one variable per experiment. 2. Reduce the failing case until only the bug remains. Localize by boundary: data, service, integration, application, infrastructure. 3. Debugging should improve the human's failure model with evidence. 4. Fix causes, not symptoms. 5. For incidents, produce blameless learning with owned follow-up actions, never "human error" as a root cause. ## Workflow 1. Capture the exact symptom: command, input, output, stack trace, timing, environment. Reproduce reliably or record why reproduction isn't yet possible. 2. After the third experiment, keep a short debug log. Form one hypothesis at a time, predict what else must be true, run the smallest experiment that confirms or refutes it. 3. Before editing, state the current failure model: likely cause, evidence for it, and the observation that would disprove it. 4. Fix the identified cause. Add a regression test or operational guard before declaring fixed. ## Verification - [ ] The