debugging-and-error-recovery
by addyosmaniThe debugging-and-error-recovery skill guides systematic root-cause debugging for failing tests, broken builds, runtime errors, and regressions. It emphasizes preserving evidence, reproducing issues, diagnosing in order, fixing minimally, and verifying before moving on.
This skill scores 78/100, which means it is a solid listing candidate for directory users. It has clear triggers, a substantial stepwise debugging workflow, and enough operational detail to help agents act with less guesswork than a generic prompt, though users should still expect a text-only skill with limited ecosystem support.
- Clear, high-signal triggers for tests, builds, runtime bugs, logs, and unexpected errors.
- Strong operational guidance with a stop-the-line rule and structured triage checklist, improving agent execution.
- Substantial body content with multiple headings and concrete recovery steps, indicating more than a placeholder skill.
- No scripts, references, or support files, so users must rely on the markdown guidance alone.
- Marked experimental/test signal and no install command, which may reduce confidence for teams seeking packaged onboarding.
Overview of debugging-and-error-recovery skill
The debugging-and-error-recovery skill is a structured way to diagnose failures without guessing. It is best for developers and agents facing failing tests, broken builds, unexpected runtime behavior, noisy logs, or regressions that only appear after a change. If you need the debugging-and-error-recovery skill for Debugging, the goal is not just to “fix an error,” but to preserve evidence, reproduce the issue, and identify the root cause before making more changes.
What this skill is for
This skill is most useful when the failure is real but the cause is unclear. It pushes a stop-the-line mindset: do not keep shipping features while a known problem is unresolved. That makes it a strong fit for test-driven workflows, incident triage, and any repo where a small mistake can cascade into misleading follow-up failures.
Who should install it
Install debugging-and-error-recovery if you regularly debug code with agents and want a repeatable process instead of ad hoc prompting. It is especially useful for teams that want better handoff quality from logs, failing CI, and bug reports into a fix plan.
What makes it different
The main value is discipline: reproduce first, preserve evidence, diagnose in order, then verify the fix and guard against recurrence. That is more decision-ready than a generic “debug this” prompt because it tells the agent how to behave when the first attempt fails.
How to Use debugging-and-error-recovery skill
Install and load the skill
Use the debugging-and-error-recovery install flow from the repo manager, then start by reading SKILL.md. In this repository, there are no helper scripts or supporting folders, so the skill is intentionally lightweight and centered on one clear process rather than a large toolchain.
Turn a vague bug into a usable prompt
The debugging-and-error-recovery usage works best when you provide three things up front: the symptom, the evidence, and the boundary. For example, instead of “fix my app,” say: “npm test fails on user-auth.spec.ts after commit abc123; here is the stack trace, the expected behavior, and the last known good run.” That gives the skill enough context to reproduce and triage instead of inventing a theory.
Suggested workflow for best results
Start by asking the agent to preserve evidence and reproduce the issue before changing code. Then have it walk the triage steps in order: reproduce, isolate, inspect recent changes, identify the root cause, fix minimally, and verify. This workflow matters because the skill is optimized for debugging-and-error-recovery, not for feature expansion or broad refactoring.
Read these repository files first
For this repo, the first file to read is SKILL.md. There are no extra references, rules, or scripts to consult, which makes adoption simpler but also means you should supply your own project-specific constraints, commands, and environment details in the prompt.
debugging-and-error-recovery skill FAQ
Is this better than a normal debugging prompt?
Usually yes, if you want consistency. A normal prompt can ask for a fix, but debugging-and-error-recovery adds a process: stop, preserve evidence, reproduce, diagnose in order, and verify. That reduces “quick fix” behavior that often hides the real problem.
When should I not use it?
Do not use it for speculative architecture work, feature planning, or tasks where there is no observable failure. If you are exploring design options rather than recovering from an error, the debugging-and-error-recovery guide is probably too restrictive for the job.
Is it beginner-friendly?
Yes, because the process is explicit. Beginners benefit from the fact that the skill tells them what to collect and in what order to investigate. The main limitation is that beginners still need to provide a real symptom, not just a general request for help.
Does it fit typical agent workflows?
Yes. It fits well when an agent has access to logs, tests, diffs, and a runnable environment. It is less useful if the agent cannot inspect evidence or verify changes, because the recovery loop depends on feedback.
How to Improve debugging-and-error-recovery skill
Give stronger failure input
The best way to improve debugging-and-error-recovery output is to include the exact failure mode, the command that triggered it, the expected result, the observed result, and recent changes. For example: “pnpm test fails only on Linux after upgrading zod; here is the diff and the stack trace.” That narrows the search space immediately.
Preserve context the skill can act on
Include logs, screenshots, repro steps, environment details, and any known good baseline. The skill works better when it can compare “before” and “after” instead of starting from a blank description. If the bug is intermittent, say so and explain what makes it more likely.
Ask for minimal fixes and verification
A strong debugging-and-error-recovery usage prompt should ask for the smallest safe fix, plus a verification plan or test update. That helps prevent overcorrection and makes the output more install-worthy for teams that care about stability.
Iterate after the first attempt
If the first pass is inconclusive, refine the prompt with the next best evidence: narrowed repro steps, a more specific stack trace, or the exact file path suspected. The debugging-and-error-recovery skill improves most when each iteration removes uncertainty rather than restating the same symptom.