ralphctl-debugging-and-error-recoverylisted

# Debugging and Error Recovery > Adapted from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) (MIT). > Adapted for ralphctl's harness contract. Systematic debugging with structured triage. When something breaks, stop adding features, preserve evidence, and follow a structured process to find and fix the root cause. Guessing wastes time. The triage checklist works for test failures, build errors, runtime bugs, and unexpected behaviour across any project ecosystem. ## When this applies - **Refine** — when a bug is part of the acceptance criteria, name it as a checkable predicate (reproduce + expected vs actual), not vague prose. - **Plan** — when tasks involve fixing existing failures, order them reproduce → localize → fix → guard so each task has a clear entry/exit contract. - **Execute** — whenever something unexpected happens during implementation: a test fails, the build breaks, behaviour diverges from the spec. Stop, triage, fix the root cause, then resume. ## The Stop-the-Line Rule When anything unexpected happens: 1. **Stop** adding features or making unrelated changes. 2. **Preserve** evidence — error output, logs, repro steps. Do not overwrite or discard. 3. **Diagnose** using the triage checklist below. 4. **Fix** the root cause, not the symptom. 5. **Guard** against recurrence by including a regression test in the same change. 6. **Resume** only after the fix is verified with the project's narrow check gate. Do not push past a failing te