Debugging and error recovery

Skill vignesh2027/AI-AGENT-SKILLS/skills/debugging-and-error-recovery

Turn your ai agent into senior engineer..The result is fast code that fails slowly. AI Agent Skills solves this by giving agents the same disciplined workflows senior engineers use

Install

npx -y skills add vignesh2027/AI-AGENT-SKILLS --skill debugging-and-error-recovery

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Systematic root-cause analysis — stop guessing, start isolating

SKILL.md

2.3 KB, as published. Nobody here has run it

Overview

Debugging is a skill, not luck. Effective debugging is systematic: form a hypothesis, design a minimal test, validate or falsify, repeat. Random changes are not debugging — they are gambling.

When to Use

When a test is failing and the cause is unclear
When behavior in production differs from behavior in development
When you've been debugging the same issue for more than 30 minutes

Process

Step 1: Reproduce reliably

Before investigating: reproduce the issue consistently. If you can't reproduce it, you can't verify you've fixed it.

Step 2: Gather evidence

Read the full error message (not just the last line). Check: logs, stack traces, metrics, recent changes. What changed recently?

Step 3: Form a hypothesis

Write down a specific, falsifiable hypothesis: "I believe the error is caused by X because of Y."

Step 4: Isolate the smallest reproduction

Create the simplest possible test case that reproduces the issue. Remove everything that is not necessary for the bug to manifest.

Step 5: Test the hypothesis

Design an experiment that will either confirm or falsify your hypothesis. This often means: add a log statement, write a unit test, or add an assertion.

Step 6: Falsify or confirm

If the evidence falsifies your hypothesis: form a new hypothesis. If it confirms: find the root cause (not just the symptom).

Step 7: Fix and verify

Fix the root cause, not the symptom. Verify the fix: the minimal reproduction must no longer reproduce. The full test suite must pass.

Step 8: Write a regression test

Write a test that would have caught this bug. Add it to the test suite.

Anti-Rationalizations

"I'll try changing this and see if it works" This is not debugging. Form a hypothesis first.

"The bug is intermittent — I can't reproduce it" Intermittent bugs have causes. Add logging and wait for the next occurrence. Or: analyze the conditions under which it occurred and stress test those conditions.

Verification Requirements

Issue reproducible before fix attempted
Root cause identified (not just symptom addressed)
Fix verified with minimal reproduction
Regression test added