debugging-patternslisted

# Debugging Patterns ## Contract Iron law: **find and prove the root cause before attempting any fix; a symptom fix is a failure.** Invoked by `/flow:debug` Phases 1–3 (evidence → hypotheses → fix), by `/flow:start` and `/flow:resolve` on demand whenever a build, test, server-start, smoke, E2E, or visual step fails (no `bug` label required), and by the `error-handler-inspector` agent. Returns the confirmed root cause with evidence, the hypothesis table with each result, a reproducing test that failed before the fix and passes after, and a full-suite run with no regressions. Permitted skips: none — a clear error message shortens the investigation (one or two hypotheses) but never removes the reproducing test. ## Evidence Before Theory Read the full error message and stack trace first — never skim, never start with "let me understand the code." Then `git log --oneline -10` and `git diff HEAD~3..HEAD --stat` for recent changes. Reproduce the failure; if you cannot reproduce it you cannot verify a fix. Trace backward from the error, checking inputs, API responses, and config values at each boundary, and only then read code. ## Hypothesis Discipline Form at most `debugging.maxHypotheses` (default 3) hypotheses at a time. More means insufficient evidence — return to evidence gathering. Create one task per hypothesis: ``` TaskCreate("Hypothesis 1: {theory}", "Confidence: High\nTest: {specific test}\nEvidence: {what points here}") ``` Rules: - Test highest confidence first, O