Peopleforrester Claude Dotfiles Debugging Assistant

Debugging Assistant

Systematic approach to finding and fixing bugs.

When to Use

• User reports a bug or error
• Something isn't working as expected
• Error messages or stack traces appear
• Tests are failing unexpectedly

Debugging Mindset

"Debugging is like being a detective in a crime movie where you're also the murderer."

Key principles:

• Don't guess - investigate systematically
• Reproduce before fixing
• Understand before changing
• One change at a time

The Debugging Process

1. REPRODUCE - Can you make it happen consistently?
   ↓
2. ISOLATE - Where exactly does it fail?
   ↓
3. UNDERSTAND - Why does it fail?
   ↓
4. FIX - Make the minimal change
   ↓
5. VERIFY - Does the fix work? Any side effects?
   ↓
6. PREVENT - Add test, improve code

Step 1: Reproduce

Before anything else, reproduce the bug consistently.

Questions to Ask

• What are the exact steps to reproduce?
• What input data triggers the bug?
• Does it happen every time or intermittently?
• What environment? (browser, OS, Node version)

Create Minimal Reproduction

// Reduce to smallest case that shows the bug
const input = { userId: null }; // This specific input
const result = processUser(input); // This call
// Expected: throws error
// Actual: returns undefined, causing crash later

Step 2: Isolate

Narrow down where the problem occurs.

Binary Search Approach

1. Add log/breakpoint in middle of suspected code
2. Is the bug before or after this point?
3. Repeat, halving the search space

Useful Commands

# Git bisect to find breaking commit
git bisect start
git bisect bad HEAD
git bisect good v1.0.0
# Git will binary search through commits

# Check if issue exists in specific version
git checkout <commit-hash>
npm test

Logging Strategy

console.log('=== DEBUG processUser ===');
console.log('Input:', JSON.stringify(input, null, 2));
console.log('User from DB:', user);
console.log('After transform:', transformed);
console.log('=========================');

Step 3: Understand

Don't fix what you don't understand.

Read the Error Message

TypeError: Cannot read property 'name' of undefined
    at processUser (src/users.ts:42:15)
    at handleRequest (src/api.ts:18:10)

This tells you:

• Error type: TypeError
• What failed: accessing .name on undefined
• Where: src/users.ts line 42
• Call stack: handleRequest → processUser

Common Error Patterns

Hypothesis Testing

1. Form hypothesis: "The bug occurs because X"
2. Make prediction: "If X is true, then Y should happen"
3. Test prediction
4. Refine hypothesis based on result

Step 4: Fix

Make the minimal change that fixes the bug.

Good Fix

// Add null check where the crash occurs
function processUser(input: Input) {
  if (!input.userId) {
    throw new Error('userId is required');
  }
  // ... rest of function
}

Bad Fix

// Don't just suppress the error
function processUser(input: Input) {
  try {
    // ... entire function wrapped in try/catch
  } catch (e) {
    return null; // Hides the real problem
  }
}

Step 5: Verify

Ensure the fix works and doesn't break anything else.

# Run the reproduction case
npm test -- --grep "specific test"

# Run full test suite
npm test

# Manual testing if applicable

Step 6: Prevent

Stop this bug from recurring.

// Add test for the bug
it('should throw error when userId is null', () => {
  const input = { userId: null };
  expect(() => processUser(input)).toThrow('userId is required');
});

Debugging Tools

Browser DevTools

• Console: Errors, logs
• Network: Failed requests, slow responses
• Sources: Breakpoints, step through code
• Performance: Find slow operations

Node.js

# Inspect mode
node --inspect src/index.js

# Debug specific test
node --inspect-brk node_modules/.bin/vitest run src/test.ts

VS Code Launch Config

{
  "type": "node",
  "request": "launch",
  "name": "Debug Tests",
  "program": "${workspaceFolder}/node_modules/.bin/vitest",
  "args": ["run", "--no-coverage"],
  "console": "integratedTerminal"
}

Common Bug Categories

When You're Stuck

1. Take a break - fresh eyes help
2. Explain the problem out loud (rubber duck debugging)
3. Simplify - remove code until bug disappears
4. Check recent changes - git diff, git log
5. Search for the error message
6. Ask for help with specific details

Converted and distributed by TomeVault — claim your Tome and manage your conversions.