/debug
Hypothesis-driven debugging that survives session crashes.
When to use
Section titled “When to use”- Something is broken and you don’t know why
- Previous fix attempts haven’t worked
- Need structured investigation, not guessing
What it does
Section titled “What it does”- Gather evidence — read the error, check logs, check browser devtools (KaBOOM MCP for web issues)
- Form hypotheses — ranked by likelihood
- Test — design the smallest experiment that eliminates a hypothesis
- Narrow — update hypothesis rankings based on results
- Fix — once root cause is confirmed, fix with TDD
State persists in specs/DEBUG.md. If the session dies mid-debug, the next session reads the file and continues — never re-tries eliminated hypotheses.
Circuit breaker: After 3 failed hypothesis cycles, stops and asks for more context.
Output
Section titled “Output”A committed fix, and specs/DEBUG.md with the full investigation trail. Appends to specs/LEARNINGS.md.