debug-hypothesislisted

# Hypothesis-Driven Debugging A four-phase loop that turns debugging from "try random fixes and hope" into a disciplined investigation. Each phase has a goal, hard rules, and a rationalization table for the excuses an agent will invent to skip it. The core principle: **you may not write a fix until you have evidence that your hypothesis is correct.** Guessing is not debugging. ## When to Use - A test fails and the cause is not immediately obvious - The same bug has been "fixed" twice and came back - The agent tried a fix that didn't work — stop it from trying another - A crash or error message you haven't seen before - Performance regression with no obvious culprit - Behavior differs between environments (local vs CI, dev vs prod) - The agent is stuck in a loop, applying the same wrong fix ## When NOT to Use - Typos, missing imports, or syntax errors — just fix them - Build failures with an obvious single-line cause - Compiler/linter messages that tell you exactly what and where - You already know the root cause and just need to write the fix If the bug survived one fix attempt, switch to this skill immediately. ## The Debug Loop ``` OBSERVE ──▶ HYPOTHESIZE ──▶ EXPERIMENT ──▶ CONCLUDE │ │ │ │ ▼ ▼ ▼ ▼ Gather List 3-5 One minimal Root cause symptoms, possible test per confirmed reproduce causes + hyp