Debugging and error recovery

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

Systematic root-cause analysis — stop guessing, start isolatingFrom its SKILL.md

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.

SKILL.md

2.3 KB, 486 tokens by cl100k_base, 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

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.