debug-detective

name	debug-detective
description	Systematic debugging approach for ANY codebase, ANY language, ANY bug type. Use when facing unexpected behavior, crashes, performance issues, or intermittent problems.

Debug Detective - Systematic Bug Hunting

🎯 When to Use This Skill

Use when facing ANY bug:

• Unexpected behavior
• Crashes or errors
• Performance issues
• Intermittent problems
• "Works on my machine" issues

⚡ Quick Start (Find bugs in 5 steps)

The Universal Debug Protocol:

1. REPRODUCE - Can you make it happen again?
2. ISOLATE - Where exactly is it breaking?
3. UNDERSTAND - Why is it breaking?
4. FIX - Apply minimal solution
5. VERIFY - Confirm fix works

🔍 Step 1: REPRODUCE

WITH MCP Tools:

"Help me create a minimal reproduction for this bug: [describe bug]"

WITHOUT MCP:

# Document the exact steps:
echo "=== BUG REPRODUCTION ===" > bug_report.md
echo "1. Start the app with: [command]" >> bug_report.md
echo "2. Navigate to: [location]" >> bug_report.md
echo "3. Perform action: [action]" >> bug_report.md
echo "4. Expected: [what should happen]" >> bug_report.md
echo "5. Actual: [what actually happens]" >> bug_report.md

# Try to reproduce 3 times - is it consistent?

Quick Tests:

# Different environments
NODE_ENV=production npm start  # Production mode?
npm start --debug              # Debug mode?
docker run ...                 # Container issue?

# Different data
# - With empty database
# - With large dataset
# - With special characters
# - With null/undefined values

🎯 Step 2: ISOLATE

WITH MCP (Architecture Analyzer):

"Trace the execution flow for [feature name]"
"Find all places where [variable/function] is used"

WITHOUT MCP:

Binary Search Method:

# Cut the problem in half repeatedly
# 1. Add midpoint log
console.log('=== MIDPOINT: Data here:', data);

# 2. Did error occur before or after?
# 3. Repeat in that half

Breadcrumb Trail:

// Add numbered checkpoints
console.log('🔍 1: Starting process');
console.log('🔍 2: Data loaded:', data);
console.log('🔍 3: Processing complete');
console.log('🔍 4: Saving results');
// Where does it stop?

Git Bisect (for regressions):

git bisect start
git bisect bad HEAD           # Current version is broken
git bisect good v1.2.3         # This version worked
# Git will help find the breaking commit

🧠 Step 3: UNDERSTAND

WITH MCP (Smart Reviewer):

"Analyze this function for potential issues: [paste code]"
"What could cause [error message]?"

WITHOUT MCP:

The 5 Whys Technique:

Problem: App crashes on user login
Why? → Authentication fails
Why? → Token is invalid
Why? → Token expired
Why? → Refresh mechanism broken
Why? → API endpoint changed
Root cause found!

Common Bug Patterns Check:

Race Conditions:

// Look for async without await
someAsyncCall(); // Missing await?
doSomethingElse(); // This runs immediately!

// Fix:
await someAsyncCall();
doSomethingElse();

Off-by-One Errors:

// Check loop boundaries
for (let i = 0; i <= array.length; i++)  // Should be < not <=

Type Mismatches:

// Check for type coercion issues
'1' + 1 === '11'; // String concatenation
'1' - 1 === 0; // Number coercion

Null/Undefined:

// Add defensive checks
const result = data?.user?.name ?? 'default';

🔧 Step 4: FIX

WITH MCP (Refactor Assistant):

"Fix this bug with minimal changes: [describe issue and paste code]"

WITHOUT MCP:

Minimal Fix Approach:

1. Smallest possible change that fixes the issue
2. Don't refactor while fixing (separate concerns)
3. Add defensive code to prevent recurrence
4. Document the fix with a comment

Fix Template:

// BUG FIX: [Issue description]
// Problem: [What was wrong]
// Solution: [What this fixes]
// Date: [Today's date]
// TODO: Consider refactoring in future

// Original problematic code (commented):
// if (user.role == 'admin') {

// Fixed code:
if (user && user.role === 'admin') {
  // Added null check and strict equality
}

✅ Step 5: VERIFY

WITH MCP (Test Generator):

"Generate a test that verifies this bug is fixed"

WITHOUT MCP:

Verification Checklist:

# 1. Original bug fixed?
[Run reproduction steps]

# 2. No new bugs introduced?
npm test
npm run lint

# 3. Edge cases handled?
# - Null inputs
# - Empty arrays
# - Large numbers
# - Special characters

# 4. Performance unchanged?
time npm start  # Basic performance check

Regression Test:

// Add a test to prevent this bug from returning
describe('Bug #123 - Login crash', () => {
  it('should handle expired tokens gracefully', () => {
    const expiredToken = generateExpiredToken();
    expect(() => authenticate(expiredToken)).not.toThrow();
    expect(authenticate(expiredToken)).toBe(false);
  });
});

🚨 Emergency Debug Tools

Universal Quick Checks:

Memory Issues:

# Node.js
node --inspect app.js  # Open chrome://inspect

# Python
python -m memory_profiler script.py

# Java
jmap -dump:file=heap.bin <pid>

CPU Issues:

# Linux/Mac
top -p <pid>

# Node.js
node --prof app.js
node --prof-process isolate-*.log

Network Issues:

# Check requests
curl -v https://api.example.com
netstat -an | grep LISTEN
tcpdump -i any port 3000

🎯 Debug Strategies by Bug Type

"Works on my machine":

1. Check environment variables
2. Compare dependency versions
3. Check OS-specific code
4. Verify file paths (case sensitivity!)
5. Check timezone/locale differences

Intermittent bugs:

1. Add extensive logging
2. Check race conditions
3. Monitor resource usage
4. Check external dependencies
5. Use stress testing

Performance degradation:

1. Profile before/after
2. Check database queries
3. Look for N+1 problems
4. Check caching
5. Monitor memory leaks

💡 Pro Tips

The Rubber Duck Method:

1. Explain the bug to a rubber duck (or colleague)
2. Step through the code line by line
3. Often, you'll spot the issue while explaining

Fresh Eyes Technique:

# After 30 minutes stuck:
git stash          # Save work
git checkout main  # Fresh perspective
# Take a 5-minute break
git stash pop      # Return with fresh eyes

Sanity Checks:

# Is it plugged in?
- Server running?
- Database connected?
- Correct branch?
- Dependencies installed?
- Environment variables set?

📝 Debug Log Template

Keep a debug log for complex issues:

## Bug: [Description]

**Date:** [Date]
**Severity:** Critical/High/Medium/Low

### Symptoms:

-

### Reproduction:

1.

### Hypotheses Tested:

- [ ] Hypothesis 1: [Result]
- [ ] Hypothesis 2: [Result]

### Solution:

-

### Lessons Learned:

-

Remember: Every bug is a learning opportunity! 🐛→📚