SKILL.md

Debugger

An advanced debugging specialist that helps diagnose and resolve code issues systematically.

When This Skill Activates

Activates when you:

Report an error or bug

Mention "debug this" or "help debug"

Describe unexpected behavior

Ask why something isn't working

Debugging Process

Phase 1: Understand the Problem

Reproduce the issue

What are the exact steps to reproduce?

What is the expected behavior?

What is the actual behavior?

What error messages appear?

Gather context

# Check recent changes

git log --oneline -10

# Check error logs

tail -f logs/error.log

# Check environment

env | grep -i debug

Phase 2: Isolate the Issue

Locate the error source

Stack trace analysis

Error code lookup

Log correlation

Narrow down scope

Binary search (comment out half)

Minimize reproduction case

Identify affected components

Phase 3: Analyze the Root Cause

#### Common Error Categories

Phase 4: Form Hypotheses

For each potential cause:

Form a hypothesis

Create a test to validate

Run the test

Confirm or reject

Phase 5: Fix and Verify

Implement the fix

Add logging if needed

Test the fix

Add regression test

Debugging Commands

General Debugging

# Find recently modified files

find . -type f -mtime -1 -name "*.js" -o -name "*.ts" -o -name "*.py"

# Grep for error patterns

grep -r "ERROR\|FATAL\|Exception" logs/

# Search for suspicious patterns

grep -r "TODO\|FIXME\|XXX" src/

# Check for console.log left in code

grep -r "console\.log\|debugger" src/

Language-Specific

JavaScript/TypeScript:

# Run with debug output

NODE_DEBUG=* node app.js

# Check syntax

node -c file.js

# Run tests in debug mode

npm test -- --inspect-brk

Python:

# Run with pdb

python -m pdb script.py

# Check syntax

python -m py_compile script.py

# Verbose mode

python -v script.py

Go:

# Race detection

go run -race main.go

# Debug build

go build -gcflags="-N -l"

# Profile

go test -cpuprofile=cpu.prof

Common Debugging Patterns

Pattern 1: Divide and Conquer

# When you don't know where the bug is:

def process():

    step1()

    step2()

    step3()

    step4()

# Comment out half:

def process():

    step1()

    # step2()

    # step3()

    # step4()

# If bug disappears, uncomment half of commented:

def process():

    step1()

    step2()

    # step3()

    # step4()

# Continue until you isolate the bug

Pattern 2: Add Logging

// Before (mysterious failure):

async function getUser(id: string) {

  const user = await db.find(id);

  return transform(user);

}

// After (with logging):

async function getUser(id: string) {

  console.log('[DEBUG] getUser called with id:', id);

  const user = await db.find(id);

  console.log('[DEBUG] db.find returned:', user);

  const result = transform(user);

  console.log('[DEBUG] transform returned:', result);

  return result;

}

Pattern 3: Minimal Reproduction

// Complex code with bug:

function processBatch(items, options) {

  // 100 lines of complex logic

}

// Create minimal reproduction:

function processBatch(items, options) {

  console.log('Items:', items.length);

  console.log('Options:', options);

  // Test with minimal data

  return processBatch([items[0]], options);

}

Error Message Analysis

Common Error Messages

Error

Likely Cause

Solution

Cannot read property 'X' of undefined

Accessing property on null/undefined

Add null check, use optional chaining

X is not a function

Wrong type, shadowing

Check typeof, verify import

Unexpected token

Syntax error

Check line before error, validate syntax

Module not found

Import path wrong

Check relative path, verify file exists

EADDRINUSE

Port already in use

Kill existing process, use different port

Connection refused

Service not running

Start service, check port

Timeout

Request too slow

Increase timeout, check network

Debugging Checklist

I can reproduce the issue consistently

I have identified the exact error location

I understand the root cause

I have a proposed fix

The fix doesn't break existing functionality

I've added a test to prevent regression

Scripts

Generate a debug report:

python scripts/debug_report.py <error-message>

References

references/checklist.md - Debugging checklist

references/patterns.md - Common debugging patterns

references/errors.md - Error message reference

debugger