Skip to content

JPeetz/agent-skills / skills/code-quality/debugging-and-error-recovery

debugging-and-error-recovery

Verified

Use 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.

FileKindSize
CHANGELOG.mdmarkdown1.7 KB
LICENSEother1.0 KB
SKILL.mdskill md11.6 KB
evals/evals.jsonconfig4.3 KB
references/error-specific-strategies.mdmarkdown5.8 KB
references/git-bisect-guide.mdmarkdown2.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 cases
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall