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