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:

• REPRODUCE - Can you make it happen again?

• ISOLATE - Where exactly is it breaking?

• UNDERSTAND - Why is it breaking?

• FIX - Apply minimal solution

• 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:

• Smallest possible change that fixes the issue

• Don't refactor while fixing (separate concerns)

• Add defensive code to prevent recurrence

• 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":

• Check environment variables

• Compare dependency versions

• Check OS-specific code

• Verify file paths (case sensitivity!)

• Check timezone/locale differences

Intermittent bugs:

• Add extensive logging

• Check race conditions

• Monitor resource usage

• Check external dependencies

• Use stress testing

Performance degradation:

• Profile before/after

• Check database queries

• Look for N+1 problems

• Check caching

• 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:

Hypotheses Tested:

• Hypothesis 1: [Result]
• Hypothesis 2: [Result]

Solution:

Lessons Learned:

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