Debugging And Error Recovery

When tests fail or builds break, this is the structured process you follow instead of guessing your way through fixes. It walks you through the stop-the-line rule (don't push past failures), a six-step triage checklist from reproduction to verification, and specific patterns for test failures, build errors, and runtime bugs. The bisection approach for regressions and the minimal reproduction guidance are solid. What I appreciate is the insistence on fixing root causes rather than symptoms, like fixing a duplicate-generating SQL query instead of deduplicating in the UI. It includes fallback patterns for when you're under time pressure, plus practical advice on when to add logging and when to remove it.

skills.sh installs: 72.4K
GitHub stars: 114.6K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add addyosmani/agent-skills --skill debugging-and-error-recovery --agent claude-code

Installs into .claude/skills of the current project.

Files

Debugging and Error Recovery

Overview

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 production incidents.

When to Use

Tests fail after a code change
The build breaks
Runtime behavior doesn't match expectations
A bug report arrives
An error appears in logs or console
Something worked before and stopped working

The Stop-the-Line Rule

When anything unexpected happens:

1. STOP adding features or making changes
2. PRESERVE evidence (error output, logs, repro steps)
3. DIAGNOSE using the triage checklist
4. FIX the root cause
5. GUARD against recurrence
6. RESUME only after verification passes

Don't push past a failing test or broken build to work on the next feature. Errors compound. A bug in Step 3 that goes unfixed makes Steps 4-6 wrong.