Debugging Skill

Purpose

Provide systematic debugging methodology for all types of bugs: runtime errors, test failures, logic bugs, performance issues, and production incidents.

Core Methodology

Five-Step Universal Framework

1. REPRODUCE - Make the bug happen reliably
2. ISOLATE - Narrow down where the problem is
3. DIAGNOSE - Understand why it's happening
4. FIX - Implement the solution
5. VERIFY - Confirm fix works and doesn't break anything

This applies to every debugging scenario without exception.

Runtime Detection Pattern

Projects use different runtimes (npm, bun, deno). Always detect before running commands:

if [ -f "bun.lockb" ]; then
  # bun project
elif [ -f "deno.json" ] || [ -f "deno.lock" ]; then
  # deno project
else
  # npm/pnpm/yarn project
fi

Debugging Scenarios

Runtime Errors (Crashes/Exceptions)

Reproduce: Capture full error with stack trace and context
Isolate: Identify exact line and values at failure
Diagnose: Type error, logic error, or environment issue?
Fix: Add validation, handle error case, fix root cause
Verify: Add test case for the error scenario

Test Failures

Reproduce: Run test in isolation with verbose output
Isolate: Read failure message, check expected vs actual
Diagnose: Async issues, mock problems, environment differences, shared state
Fix: Fix implementation or test, add better assertions
Verify: Run test multiple times to ensure stability

Logic Bugs (Wrong Behavior)

Reproduce: Create minimal reproduction with input/output comparison
Isolate: Add console.logs/breakpoints at each step
Diagnose: Use scientific method - form hypothesis, test it
Fix: Off-by-one, wrong condition, state mutation, edge cases
Verify: Add test for the specific broken case

Performance Issues

Reproduce: Measure with console.time or performance.now
Isolate: Use profiler, binary search slow sections
Diagnose: N+1 queries, large data, sync ops, memory leaks, inefficient algorithms
Fix: Optimize algorithm (O(n²) → O(n)), add caching, parallelize
Verify: Benchmark before and after

Production Issues

Reproduce: Check logs, try to reproduce with production-like conditions
Isolate: Identify differences between local and production
Diagnose: Review logs, check monitoring, verify external services
Fix: Add defensive code, graceful degradation, retry logic
Verify: Deploy to staging, test with production-like data, monitor closely

Key Tools

Browser DevTools

• debugger - Stop execution
• Conditional breakpoints - Break only when condition true
• console.table() - Format objects
• console.trace() - Show call stack
• Network tab - Check requests/responses

Git Bisect

Find exactly when a bug was introduced by binary searching commit history.

Type Debugging (TypeScript)

type Debug<T> = T extends infer U ? U : never;
const test: never = value; // Force error to see inferred type

Binary Search Debugging

Comment out half the code. Bug still happens? It's in the other half. Repeat.

Common Anti-Patterns

❌ Random changes without hypothesis
✅ Form hypothesis based on evidence, test it

❌ No reproduction before fixing
✅ Create minimal test case first

❌ Masking errors with empty catch blocks
✅ Log errors, handle gracefully

❌ No documentation of the fix
✅ Add test, update docs if significant

❌ Runtime assumptions (always using npm)
✅ Detect runtime first

Integration Points

With Work Records

Document debugging sessions in work records:

• What was the bug?
• How did you find it?
• What was the fix?
• What did you learn?

With Testing

Every fixed bug should get a test to prevent regression.

With ADRs

Significant debugging decisions (architecture changes to fix performance, switching algorithms) deserve ADRs.

With Evidence Tracking

Debugging demonstrates:

• S7: Problem solving and debugging techniques
• B2: Logical thinking in diagnosis
• K9: Understanding algorithms when optimizing

Debugging Checklist

Before:

• Can you reproduce it?
• Captured error/stack trace?
• Know when it started?

During:

• Isolated problem area?
• Checked assumptions?
• Reviewed recent changes?
• Documenting attempts?

After:

• Root cause fixed?
• Test added?
• Nothing else broken?
• Solution documented?

Runtime-Specific Commands

Deno

deno test --watch path/to/test.ts
deno run --inspect-brk script.ts  # Debug with Chrome DevTools

Bun

bun test --watch path/to/test.ts
bun --inspect script.ts  # Debug
bun --hot script.ts      # Hot reload

npm

npm test -- --watch path/to/test.ts
node --inspect-brk script.js  # Debug

Reference Document

Full debugging patterns documented in: ~/.claude/debugging-workflow-patterns.md

When to Apply

This skill auto-invokes when conversation includes:

• "bug", "error", "broken", "failing", "crash"
• "test failing", "test won't pass"
• "slow", "performance", "timeout"
• "production issue", "only happens in prod"
• "TypeError", "undefined", "null"
• "works locally but not in production"

Always apply the five-step framework regardless of bug type.