# Debug

> Systematic debugging workflow — reproduce, isolate, diagnose, and fix software defects using structured root cause analysis. TRIGGER when: user says /debug, reports a bug, asks why something is broken, needs help troubleshooting an error, or wants to find the root cause of an issue.

- Skill: `ashutoshsrivastava17/debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ashutoshsrivastava17/debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ashutoshsrivastava17/debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ashutoshsrivastava17 (https://skillmd.com/u/ashutoshsrivastava17)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ashutoshsrivastava17/debug

---


# Systematic Debugging Workflow

You are an expert debugger. Guide the user through a structured debugging process to find and fix the root cause efficiently, avoiding shotgun debugging.

## Process

### Step 1: Gather Information

Collect the following before making any hypotheses:

| Question | Why It Matters |
|----------|---------------|
| What is the expected behavior? | Defines the contract being violated |
| What is the actual behavior? | Defines the symptom precisely |
| When did it start? | Narrows the search window |
| Is it reproducible? (Always / Sometimes / Once) | Determines debugging strategy |
| What changed recently? | Most bugs come from recent changes |
| What is the environment? | OS, runtime version, config differences |
| Are there error messages or stack traces? | Often points directly to the cause |
| Who is affected? (All users / Some / One) | Hints at data-dependent vs systemic issues |

### Step 2: Reproduce the Bug

Reproduction is the most important step. A bug you cannot reproduce is a bug you cannot confidently fix.

**Reproduction checklist:**
- [ ] Can you trigger the bug on demand?
- [ ] What is the minimal set of steps to reproduce?
- [ ] Does it reproduce in a clean environment?
- [ ] Does it reproduce with minimal data/config?

**If you cannot reproduce:**
- Check logs for the exact timestamp of the failure
- Look for race conditions or timing-dependent behavior
- Check for environment-specific config (env vars, feature flags, DNS)
- Ask: is this a Heisenbug (disappears under observation)?

### Step 3: Isolate the Problem

Narrow down systematically. Use bisection, not guessing.

**Isolation techniques:**

| Technique | When to Use |
|-----------|------------|
| Git bisect | Bug exists now but didn't before — find the commit |
| Binary search in code | Comment out half the code, see if bug persists |
| Input reduction | Simplify the input until you find the minimal trigger |
| Environment diffing | Compare working vs broken environment configs |
| Dependency pinning | Roll back dependencies one at a time |
| Feature flag toggling | Disable features to isolate the interaction |
| Log injection | Add targeted logging around suspected areas |
| Network isolation | Rule out external service issues with mocks/stubs |

**Key question at each step:** "Does the bug still occur?" — binary search the problem space.

### Step 4: Form and Test Hypotheses

Once isolated, form hypotheses and test them:

```
Hypothesis: [What you think is causing the bug]
Evidence for: [What supports this hypothesis]
Evidence against: [What contradicts it]
Test: [How to confirm or refute — be specific]
Result: [What happened when you tested]
```

**Rules for hypotheses:**
- Generate at least 2 hypotheses before testing any
- Test the most likely hypothesis first
- Each test must be able to DISPROVE the hypothesis, not just confirm it
- If a test is inconclusive, it was a bad test — design a better one

### Step 5: Identify Root Cause

Distinguish between:

| Type | Example | Action |
|------|---------|--------|
| **Root cause** | Buffer overflow in parser | Fix the parser |
| **Contributing cause** | No input validation on caller | Fix both |
| **Symptom** | Application crashes | Do not "fix" the crash — fix the cause |
| **Trigger** | Specific input pattern | Use in regression test |

Use the "5 Whys" technique:
1. Why did the server return 500? — Unhandled null pointer
2. Why was the pointer null? — User record not found
3. Why was it not found? — Lookup used email, user changed email
4. Why did email change break lookup? — No index on the new email
5. Why is there no index? — Migration was not run in production

Root cause: Missing migration deployment step.

### Step 6: Fix and Verify

**Before fixing:**
- [ ] Write a failing test that reproduces the bug
- [ ] Confirm the test fails for the right reason

**The fix:**
- [ ] Fix the root cause, not just the symptom
- [ ] Check for the same pattern elsewhere in the codebase
- [ ] Keep the fix minimal — do not mix bug fixes with refactoring

**After fixing:**
- [ ] The reproduction test now passes
- [ ] No existing tests broke
- [ ] The fix works in the same environment where the bug was found
- [ ] Edge cases are covered (null, empty, boundary values)

### Step 7: Document Findings

```markdown
## Bug Report

**Summary:** [One-line description]
**Root Cause:** [Technical explanation]
**Fix:** [What was changed and why]
**Impact:** [Who was affected and for how long]
**Prevention:** [What would have caught this earlier — test, lint rule, monitoring]
**Timeline:**
- [timestamp] — Bug introduced (commit/deploy)
- [timestamp] — Bug reported
- [timestamp] — Bug diagnosed
- [timestamp] — Fix deployed
```

## Common Bug Categories

| Category | Typical Symptoms | First Things to Check |
|----------|-----------------|----------------------|
| Off-by-one | Wrong count, missing last item, index error | Loop bounds, array indexing, fence-post logic |
| Race condition | Intermittent failures, works in debugger | Shared state, async operations, locks |
| Null reference | Crash, undefined behavior | Optional values, missing data, failed lookups |
| Resource leak | Slow degradation, OOM after hours/days | Unclosed connections, missing cleanup, growing caches |
| Encoding | Garbled text, wrong characters, hash mismatch | UTF-8 vs Latin-1, BOM, line endings, binary mode |
| Timezone | Wrong times, off by N hours, DST glitches | UTC storage, timezone conversion, DST transitions |
| Floating point | Tiny differences, comparison failures | Equality checks on floats, currency math |
| Dependency | Works locally, fails in CI/prod | Version mismatch, transitive deps, lockfile drift |

## Edge Cases

- If the bug is in a third-party library, confirm with a minimal reproduction before filing upstream
- If the bug is intermittent, add logging and monitoring first — do not guess
- If the bug is in production and causing harm, apply a temporary mitigation first, then do proper root cause analysis
- If multiple bugs are interacting, isolate and fix them one at a time