devrites-debug-recovery

devrites-debug-recovery — fix the root cause, not the symptom

Disciplined recovery from failures. NO shotgun edits, NO blanket retries.

When to invoke

Loaded by /rite-prove (and during /rite-build) when something fails. Use when tests, builds, typecheck, runtime, or browser checks are red and the next move is unclear.

The six-phase cycle

1. Build the feedback loop — fast, deterministic, agent-runnable pass/fail signal. This is the skill — be aggressive here. See build-the-loop.md.
2. Reproduce — run the loop. Confirm the failure matches the user's report (not a nearby failure); capture the exact error text; confirm reproducibility (or a high enough repro rate for flaky bugs). Do not proceed without reproduction.
3. Ranked hypotheses (3-5, falsifiable) — generate the list before testing any of them. Each must state a prediction. See hypotheses.md.
4. Instrument — debugger > logs > "log everything and grep". One variable at a time. Tagged debug-log prefixes. See instrumentation.md.
5. Fix + regression test — write the regression test before the fix, but only if a correct seam exists. If no correct seam: that IS the finding; record it. See regression-test.md.
6. Cleanup + classify — repro gone, debug logs gone, throwaway harnesses gone, hypothesis recorded. Classify the failure. See cleanup-and-classify.md.

Hard rules

• Quote real error text; never paraphrase it away.
• Change one thing at a time so you know what fixed it.
• Do NOT loosen / delete a failing assertion to get green — check whether it's drift first (route via /rite-plan repair).
• Do NOT hide flakiness with sleeps / retries — characterize it.
• 3 failed attempts on the same root cause → escalate: re-hypothesize from scratch, invoke devrites-doubt, or ask the user. Don't keep trying variations of a wrong idea.