debug

Debugging Skill

Systematic approaches to investigating and diagnosing bugs.

Core Principle

Understand before fixing. A proper diagnosis leads to a proper fix.

Name

han-core:debug - Investigate and diagnose issues without necessarily fixing them

Synopsis

/debug [arguments]

Debug vs Fix

Use /debug when:

• Investigating an issue to understand it
• Need to gather information before fixing
• Want to identify root cause without implementing solution
• Triaging to determine severity/priority
• Research phase before fix

Use /fix when:

• Ready to implement the solution
• Debugging AND fixing in one go
• Issue is understood, just needs fixing

The Scientific Method for Debugging

1. Observe

Gather all the facts:

• What's the symptom? (What's happening that shouldn't?)
• When does it happen? (Always, sometimes, specific conditions?)
• Who's affected? (All users, some users, specific scenarios?)
• Error messages? (Exact text, stack traces, error codes?)
• Recent changes? (What changed before this started?)

Evidence to collect:

• Error messages and stack traces
• Application logs
• User reports
• Reproduction steps
• Environment details (browser, OS, versions)
• Network requests/responses
• Database query logs

2. Form Hypothesis

Based on symptoms, what could cause this?

Common categories:

• Logic error: Code does wrong thing
• State management: State gets out of sync
• Async/timing: Race condition, callback hell
• Data issue: Unexpected input format
• Integration: API change, service down
• Environment: Config, permissions, network
• Resource: Memory leak, connection pool exhausted

Prioritize hypotheses:

1. Most likely causes first
2. Easiest to test first (when equal likelihood)
3. Most impactful if true

3. Test Hypothesis

Design experiment to prove/disprove:

• Add logging to see values
• Add breakpoints to pause execution
• Modify input to isolate variable
• Disable feature to rule out
• Compare with working version

Keep notes:

**Hypothesis:** Database query timeout
**Test:** Add query timing logs
**Result:** Query completes in 50ms
**Conclusion:** Not the database

**Hypothesis:** Network latency
**Test:** Check network tab, add timing
**Result:** API call takes 5 seconds
**Conclusion:** Found the issue

4. Analyze Results

What did you learn?

• Hypothesis confirmed or rejected?
• New questions raised?
• Unexpected findings?
• Root cause identified?

5. Repeat or Conclude

If root cause found:

• Document findings
• Estimate impact
• Plan fix

If not found:

• Form new hypothesis
• Repeat cycle

Debugging Strategies

Strategy 1: Add Logging

Most universally useful technique:

// Strategic console.log placement
function processOrder(order) {
  console.log('processOrder START:', { orderId: order.id })

  const items = order.items
  console.log('items:', items.length)

  const validated = validate(items)
  console.log('validation result:', validated)

  if (!validated.success) {
    console.log('validation failed:', validated.errors)
    throw new Error('Invalid order')
  }

  const total = calculateTotal(items)
  console.log('total calculated:', total)

  console.log('processOrder END')
  return total
}

Logging guidelines:

• Log function entry/exit
• Log branching decisions
• Log external calls (API, database)
• Log unexpected values
• Include context (IDs, user info)

Strategy 2: Use Debugger

Interactive debugging:

// Browser
function buggyFunction(input) {
  debugger;  // Execution pauses here
  const result = transform(input)
  debugger;  // And here
  return result
}

// Node.js
node --inspect app.js
# Then open chrome://inspect in Chrome

Debugger features:

• Step over (next line)
• Step into (into function call)
• Step out (back to caller)
• Watch expressions
• Call stack inspection
• Variable inspection

Strategy 3: Binary Search

Isolate the problem area:

// 100 lines of code, bug somewhere

// Comment out lines 50-100
// Bug still happens? It's in lines 1-50

// Comment out lines 25-50
// Bug disappears? It's in lines 25-50

// Comment out lines 37-50
// Bug still happens? It's in lines 25-37

// Continue until isolated to specific lines

Strategy 4: Rubber Duck Debugging

Explain the problem out loud:

1. "This function is supposed to calculate shipping cost"
2. "It takes the weight and destination"
3. "First it... wait, it's using price instead of weight!"
4. (Bug found)

Why this works: Forces you to examine assumptions.

Strategy 5: Compare Working vs Broken

What's different?

Version comparison:

# Find which commit broke it
git bisect start
git bisect bad HEAD
git bisect good v1.0.0
# Git checks out middle commit
npm test
git bisect good/bad
# Repeat until found

Environment comparison:

• Works locally but not production?
• Works for some users but not others?
• Worked yesterday but not today?

What changed?

Strategy 6: Simplify

Reduce to minimal reproduction:

// Complex case with bug
processUserOrderWithDiscountsAndShipping(user, cart, promo, address)

// Simplify inputs one at a time
processUserOrderWithDiscountsAndShipping(user, [], null, null)
// Still breaks? Not discount or address

processUserOrderWithDiscountsAndShipping(null, [], null, null)
// Works now? It's the user object

// What about the user object causes it?

Strategy 7: Check Assumptions

Question everything:

// Assumption: API returns array
const users = await api.getUsers()
users.forEach(...)  // Crashes

// Check assumption
console.log(typeof users)  // "undefined"
console.log(users)          // undefined

// Assumption was wrong!

Common wrong assumptions:

• Function returns expected type
• Variable is defined
• Array is not empty
• API will always respond
• Async operation has completed
• State is up to date

Debugging by Symptom

"Intermittent failure"

Likely causes:

• Race condition (timing-dependent)
• Data-dependent (certain inputs trigger it)
• Resource leak (happens after N operations)
• External service flakiness

Investigation:

• Add extensive logging
• Look for async operations
• Check timing between operations
• Look for shared state
• Run many times to see pattern

"Works locally, fails in production"

Check differences:

• Environment variables
• Data (production has different/more data)
• Network (CORS, SSL, proxies)
• Dependencies (versions, OS)
• Resources (memory, connections)

"Slow performance"

Don't guess - profile:

Frontend:

• Chrome DevTools > Performance tab
• Look for long tasks (> 50ms)
• Check for layout thrashing
• Look for memory leaks

Backend:

• Add timing logs around operations
• Check database query time (EXPLAIN ANALYZE)
• Check external API call time
• Profile with APM tool

"Memory leak"

Investigation:

// Take heap snapshot
// Do operation that leaks
// Take another heap snapshot
// Compare - what increased?

Common causes:

• Event listeners not removed
• Closures holding references
• Global variables accumulating
• Intervals not cleared
• Cache growing unbounded

"Crash/Exception"

Read the stack trace:

Error: Cannot read property 'map' of undefined
    at processUsers (app.js:42:15)
    at handleRequest (app.js:23:3)
    at Server.<anonymous> (server.js:12:5)

Stack trace tells you:

• Line 42: Where it crashed
• Line 23: Where it was called from
• Line 12: Origin of the request

Then:

• Go to line 42
• Check what's undefined
• Trace back why it's undefined

"It works sometimes"

• Race condition?
• Timing issue?
• Data-dependent?
• Check for async issues

Common Bug Patterns

Null/Undefined

// Bug
function process(user) {
  return user.name.toUpperCase()  // Crashes if user is null
}

// Investigation
console.log('user:', user)  // undefined - why?
// Trace back to where user comes from

Off-by-One

// Bug
for (let i = 0; i <= array.length; i++) {  // <= instead of <
  process(array[i])  // Crashes on last iteration
}

// Investigation
console.log('i:', i, 'length:', array.length)
// Notice i === array.length causes array[i] === undefined

Async Timing

// Bug
let data
fetchData().then(result => {
  data = result
})
console.log(data)  // undefined - async not complete

// Investigation
console.log('1. Before fetch')
fetchData().then(result => {
  console.log('3. Got result')
  data = result
})
console.log('2. After fetch call')
// Output: 1, 2, 3 - async completes later

State Mutation

// Bug
function addItem(cart, item) {
  cart.items.push(item)  // Mutates input!
  return cart
}

const originalCart = { items: [] }
const newCart = addItem(originalCart, item)
// originalCart was modified - unexpected!

// Investigation
console.log('before:', originalCart)
const newCart = addItem(originalCart, item)
console.log('after:', originalCart)  // Changed!

Scope Issues

// Bug
for (var i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100)
}
// Prints: 3, 3, 3 (expected 0, 1, 2)

// Investigation
// var is function-scoped, i is shared
// By time timeout fires, loop is done, i === 3

// Fix: Use let (block-scoped) or capture i

Investigation Report Format

## Investigation: [Issue description]

### Symptoms
[What's happening that's wrong?]

### Evidence
- Error message: [exact text]
- When it happens: [conditions]
- Frequency: [always/sometimes/rarely]
- Affected users: [all/some/specific group]

### Reproduction Steps
1. [Step 1]
2. [Step 2]
3. [Observe error]

### Investigation Timeline

**Hypothesis 1:** [What I thought might be wrong]
- Tested by: [What I did to test]
- Result: [What I found]
- Conclusion: [Ruled out / Confirmed]

**Hypothesis 2:** [Next theory]
- Tested by: [What I did]
- Result: [What I found]
- Conclusion: [Ruled out / Confirmed]

### Root Cause
[What's actually causing the issue]

**Evidence:**
- [Log showing the problem]
- [Stack trace pointing to source]
- [Data showing the pattern]

### Impact
- Severity: [Critical/High/Medium/Low]
- Scope: [How many users/scenarios affected]
- Workaround: [Any temporary solutions]

### Next Steps
- [ ] [What should be done to fix]
- [ ] [Any additional investigation needed]
- [ ] [Related issues to check]

Debugging Tools

Browser Developer Tools

Console:

• console.log() - Print values
• console.table() - Display arrays/objects as table
• console.trace() - Print stack trace
• console.time() / console.timeEnd() - Measure duration

Debugger:

• Set breakpoints
• Step through code
• Inspect variables
• Watch expressions
• Call stack

Network:

• View all requests
• See request/response headers and bodies
• Measure timing
• Replay requests

Performance:

• Record profile
• See function call tree
• Identify bottlenecks
• Check memory usage

Command Line Tools

# Search for text in files
grep -r "error" logs/

# Follow log file
tail -f logs/app.log

# Search with context
grep -B 5 -A 5 "ERROR" logs/app.log

# Check disk space
df -h

# Check memory
free -m

# Check running processes
ps aux | grep node

Database Debugging

-- PostgreSQL
EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com';

-- Show slow queries
SELECT * FROM pg_stat_statements ORDER BY total_time DESC LIMIT 10;

-- Check table size
SELECT pg_size_pretty(pg_total_relation_size('users'));

-- Check indexes
\d users

Debugging Checklist

Before Starting

• Can reproduce the issue reliably?
• Have error message or symptom description?
• Know when it started happening?
• Checked if recent changes related?
• Checked logs for clues?

During Investigation

• Formed clear hypothesis?
• Testing hypothesis systematically?
• Taking notes on findings?
• Not making random changes hoping to fix?
• Questioning assumptions?

After Finding Root Cause

• Understand WHY it happens?
• Can explain it to someone else?
• Documented findings?
• Estimated impact?
• Identified proper fix?

Anti-Patterns

Random Code Changes

BAD: "Maybe if I change this... nope, try this... nope, try this..."
GOOD: "Hypothesis: X causes Y. Test: Change X. Result: Y still happens.
       Conclusion: X is not the cause."

Assuming Without Verifying

BAD: "The API must be returning valid data"
GOOD: "Let me log the API response to see what it actually returns"

Stopping at Symptoms

BAD: "The page is blank. Fixed by adding a null check."
GOOD: "The page is blank because user is null. User is null because
       authentication token expired. Root cause: token not being refreshed."

Debugging in Production

BAD: "Let me add console.log to production to see..."
GOOD: "Let me reproduce locally and debug there, or use proper logging"

No Reproduction Steps

BAD: "It crashed once, let me guess why"
GOOD: "Let me find reliable way to reproduce it first"

Examples

When the user says:

• "Why is this page loading slowly?"
• "Investigate this intermittent test failure"
• "Figure out why users are seeing this error"
• "Debug the memory leak in production"
• "What's causing the database timeouts?"

Integration with Other Skills

• Use proof-of-work skill to document evidence
• Use test-driven-development skill to add regression test after fix
• Use explain skill when explaining bug to others
• Use boy-scout-rule skill while fixing (improve surrounding code)

Notes

• Use TaskCreate to track investigation steps
• Document findings even if not fixing immediately
• Create minimal reproduction case
• Consider using /fix once root cause is found
• Add logging/metrics to prevent future issues

Remember

1. Reproduce first - If you can't reproduce, you can't debug
2. Gather evidence - Don't guess, look at data
3. Form hypothesis - What do you think is wrong?
4. Test systematically - Prove or disprove hypothesis
5. Find root cause - Not just symptoms
6. Document - Help future you and others

Debugging is detective work. Be methodical, not random.