JPeetz/agent-skills / skills/code-quality/debugging-and-error-recovery
debugging-and-error-recovery
VerifiedUse this skill when tests fail, builds break, runtime behavior doesn't match expectations, a bug report arrives, or something worked yesterday and stopped working. Guides systematic root-cause debugging with structured triage, anti-rationalization tables, and verification gates — no guessing, no skipped steps.
| File | Kind | Size |
|---|---|---|
| CHANGELOG.md | markdown | 1.7 KB |
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 11.6 KB |
| evals/evals.json | config | 4.3 KB |
| references/error-specific-strategies.md | markdown | 5.8 KB |
| references/git-bisect-guide.md | markdown | 2.3 KB |
CHANGELOG.md
View on GitHub# Changelog
## v1.0.0 (2026-09-21)
### Initial Release — Systematic Root-Cause Debugging
- **Process-driven debugging workflow:** Stop-the-Line rule, 6-step triage checklist (Reproduce → Localize → Reduce → Fix Root Cause → Guard → Verify), with decision trees at each step
- **Anti-rationalization table:** 9 common rationalizations vs reality, drawn from real debugging failures
- **Progressive disclosure:** Core SKILL.md covers the essential workflow; references/ dive deeper into git bisect, error-specific patterns, instrumentation strategies
- **Error-specific triage trees:** Test failures, build failures, runtime errors, production incidents — each with a structured decision tree
- **Verification checklist:** 6-item end-to-end checklist with [ ] markers for tracking completion
- **Safe fallback patterns:** Graceful degradation, defensive defaults, no silent swallows
- **Treatment of error output as untrusted data:** Rules for safe handling of instructions embedded in error messages
- **Red flags:** 8 explicit warning signs of superficial debugging
- **Eval suite:** 5 positive test cases covering the core workflow, anti-rationalization, error-specific triage, safe fallbacks, and verification gates
- **Validated against scripts/validate_skill.py**
### Source Attribution
Adapted and materially improved from addyosmani/agent-skills (MIT licensed). Key improvements:
- Anti-rationalization table expanded from 5 to 9 entries
- Progressive disclosure structure with references for (git bisect, error-specific strategies)
- Safe fallback patterns section added
- Error output as untrusted data section added
- Verification checklist with [ ] markers
- Expanded error-specific triage with production incident pattern
- Eval suite with 5 coverage casesRelated skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |