debugging-and-error-recovery
Guides systematic root-cause debugging. Use when tests fail, builds break, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need a systematic approach to finding and fixing the root cause rather than guessing.
Best for Development teams following…Works with GitHubLow risk
⌘source
- author
@addyosmani- language
- Shell
★17kstars
2.2kforks
Apr 18, 2026
✦overview.md
Key Features
- ·Structured triage checklist for systematic debugging
- ·Stop-the-line rule to prevent compounding errors
- ·Works for test failures, build errors, runtime bugs, and production incidents
- ·Focuses on root cause analysis rather than guessing
- ·Preserves evidence and requires verification before resuming
Use Cases
- →Tests fail after a code change
- →Build breaks during development
- →Runtime behavior doesn't match expectations
- →Bug reports arrive from users or testers
- →Errors appear in logs or console output
- →Something that worked before stops working
Best for
- ✓Development teams following systematic processes
- ✓Engineers dealing with production incidents
- ✓Projects with frequent test failures or build breaks
Not ideal for
- !Quick one-off fixes without root cause analysis
- !Situations requiring immediate workarounds over systematic fixes
FAQs
name
debugging-and-error-recovery
description
Guides systematic root-cause debugging. Use when tests fail, builds break, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need a systematic approach to finding and fixing the root cause rather than guessing.
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-10 wrong.
The Triage Checklist
Work through these steps in order. Do not skip steps.
Step 1: Reproduce
$install
1-click copynpx skills add addyosmani/agent-skills --skill debugging-and-error-recoverySafety assessment
★
Clarity score
How clear and easy to understand the SKILL.md instructions are, rated from 1 to 5.
5/ 5
excellentVery clear and well structured, with almost no room for misunderstanding.
◎
Actionability score
How directly an agent can act on the SKILL.md instructions, rated from 1 to 5.
4/ 5
highMostly actionable with clear steps; only a few small gaps remain.