/debugging

Source: ~/.claude/skills/debugging/SKILL.md

---

name: debugging description: Systematic debugging workflow for finding and fixing issues. Use when user reports a bug, tests are failing, or unexpected behavior occurs. Walks through reproduce → isolate → investigate → hypothesize → test → fix → document.

Debugging

Systematic debugging workflow for finding and fixing issues.

When to Use

• When user reports a bug
• When tests are failing
• When unexpected behavior occurs

Process

Phase 1: Reproduce

1. Get exact steps to reproduce
2. Identify expected vs actual behavior
3. Note any error messages verbatim

Phase 2: Isolate

1. Find the smallest reproducible case
2. Identify which component/file is involved
3. Check recent changes to that area:

   git log --oneline -10 -- [file]
   git diff HEAD~5 -- [file]
   

Phase 3: Investigate

1. Read the relevant code
2. Trace the execution path
3. Add strategic logging if needed:

   console.log('[DEBUG] functionName:', { input, state });
   

4. Check for common issues:
   • Null/undefined values
   • Off-by-one errors
   • Async timing issues
   • Type mismatches
   • Missing error handling

Phase 4: Hypothesize

List possible causes ranked by likelihood:

1. [Most likely cause]
2. [Second possibility]
3. [Third possibility]

Phase 5: Test Hypothesis

For each hypothesis:

1. Make minimal change to test
2. Verify if it fixes the issue
3. Verify it doesn't break other things

Phase 6: Fix

1. Implement the fix
2. Remove debug logging
3. Add test to prevent regression
4. Document root cause

Output Format

## Debug Report: [issue description]

### Reproduction
- Steps: [numbered steps]
- Expected: [what should happen]
- Actual: [what happens]

### Root Cause
[Explanation of why the bug occurred]

### Fix Applied
[Description of the fix]
- File: [path:line]
- Change: [what was changed]

### Prevention
- [ ] Added test: [test name]
- [ ] Related areas checked: [yes/no]

### Verification
- [ ] Bug no longer reproduces
- [ ] Existing tests pass
- [ ] No new issues introduced

Common Patterns

Async Issues

// Wrong: not awaiting
doAsyncThing();
useResult(); // result not ready

// Right: await
await doAsyncThing();
useResult();

Null Checks

// Wrong: assumes existence
user.profile.name

// Right: optional chaining
user?.profile?.name

Off-by-One

// Wrong: includes length
for (let i = 0; i <= arr.length; i++)

// Right: excludes length
for (let i = 0; i < arr.length; i++)