Output language: answer and write artifacts in the user's own language (match their messages, not the repo's history).
Overview
Fuses systematic root-cause debugging with verification-before-completion.
Core principle: evidence before fixes; evidence before "fixed" claims.
Announce: "Using debug to …"
When to Use
- Any bug, flaky test, build/CI failure, unexpected behavior, performance mystery
- Especially under time pressure ("just one quick fix")
- Before claiming "done" / "passing" / "fixed"
When NOT to use: pure greenfield feature with no failure (use grill / write-spec / write-plan / tdd).
The Iron Law
1. NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
2. NO "FIXED" / "PASSING" / "DONE" CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE IN THIS TURN.
Violating the letter is violating the spirit.
Workflow (phases — do in order)
Phase 1 — Investigate (no fix yet)
- Read the full error / stack / logs (don't skim)
- Reproduce consistently — if you can't, gather data, don't guess
- Check recent changes (
git diff, commits, config, env) - Multi-component systems: instrument boundaries (in → out) to see where it breaks
- Trace bad values backward to the source; plan to fix at source
Create todos for these steps; do not edit production logic until Phase 1 has a stated root cause.
Phase 2 — Pattern
- Find a working similar path in-repo
- Diff working vs broken; list every difference
- Note dependencies / assumptions
Phase 3 — Hypothesis
- One hypothesis: "X is root cause because Y"
- Design the smallest test/probe that would falsify it
- If wrong → new hypothesis (don't stack random changes)
Phase 4 — Fix via TDD
- tdd + test-design: write a failing regression that locks the bug
- Watch RED for the right reason
- Minimal fix → GREEN
- Verify (below) before any success language
Phase 5 — Verify before claims (mandatory)
Before saying fixed/passing/done/complete:
- IDENTIFY the command that proves the claim
- RUN it fresh (full command)
- READ exit code and failures
- ONLY THEN claim, with the evidence
| Claim | Requires |
|---|---|
| Tests pass | Test run output, 0 failures |
| Bug fixed | Original symptom re-tested + regression green |
| Build OK | Build exit 0 |
| Requirements met | Checklist against plan/spec |
Red-green proof for the regression: fail without fix → pass with fix (mentally or actually revert-check when feasible).
Rationalization Table
| Excuse | Reality |
|---|---|
| "Obvious one-liner" | Still need cause + regression test. |
| "Should work now" | RUN verification. |
| "I'm confident / tired" | Confidence ≠ evidence. |
| "Logged something, good enough" | Boundary evidence must show where. |
| "Fix first, understand later" | That's how you get two bugs. |
Red Flags — STOP
- Proposing a fix before stating root cause
- "Should", "probably", "seems" success wording
- Commit/PR of a fix without fresh test/symptom proof
- Shotgun changes across unrelated files
- Skipping the failing regression test
Checklist
- Root cause stated with evidence
- Failing regression (tdd) observed RED then GREEN
- Fresh verification command run this turn
- Claim includes that evidence
- No unrelated drive-by edits
Hand-off
Transition gate — before the fix ships, ask the user (one AskUserQuestion; never auto-advance):
A) Recommended: Proceed → review (then commit-and-push)
B) Review first — run **review** on the fix (`references/code.md`; upstream = the failing repro), then return to this gate
C) Adjust — back into debug for the un-locked edge, then return to this gate
D) Something else (I will type it)
- Structure was the cause → solid
- Ship the fix → review + commit-and-push