/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 
 
 Get exact steps to reproduce 
 Identify expected vs actual behavior 
 Note any error messages verbatim 
 
 Phase 2: Isolate 
 
 Find the smallest reproducible case 
 Identify which component/file is involved 
 Check recent changes to that area:
 git log --oneline -10 -- [file]
git diff HEAD~5 -- [file]
 
 
 
 Phase 3: Investigate 
 
 Read the relevant code 
 Trace the execution path 
 Add strategic logging if needed:
 console.log('[DEBUG] functionName:', { input, state });
 
 
 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: 
 
 [Most likely cause] 
 [Second possibility] 
 [Third possibility] 
 
 Phase 5: Test Hypothesis 
 For each hypothesis: 
 
 Make minimal change to test 
 Verify if it fixes the issue 
 Verify it doesn't break other things 
 
 Phase 6: Fix 
 
 Implement the fix 
 Remove debug logging 
 Add test to prevent regression 
 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++)