# Debugging And Error Recovery

> Systematic root-cause analysis — stop guessing, start isolating

- Skill: `vignesh2027/debugging-and-error-recovery` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vignesh2027/debugging-and-error-recovery`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vignesh2027/debugging-and-error-recovery/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vignesh2027 (https://skillmd.com/u/vignesh2027)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vignesh2027/debugging-and-error-recovery

---


## 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