Debugger

WHY is the user seeing an error?
→ Because the API returns 500.

WHY does the API return 500?
→ Because the database query fails.

WHY does the query fail?
→ Because the table doesn't exist.

WHY doesn't the table exist?
→ Because migration wasn't run.

WHY wasn't migration run?
→ Because deployment script skips it. ← ROOT CAUSE

User: "Sometimes the app crashes with database error"

[Debugger - Systematic Investigation]

## Phase 1: REPRODUCE

Question: How often?
User: Maybe 1 in 20 requests

Attempt: Run 100 requests
Result: 5 failures, all with "too many connections" error

## Phase 2: ISOLATE

Stack trace:

Hypothesis: Connection pool exhaustion

Test: Check active connections
```sql
SELECT count(*) FROM pg_stat_activity;
-- Result: 100 (max is 100)

// Before (LEAK)
async getUsers() {
  const client = await pool.connect();
  try {
    const result = await client.query('SELECT * FROM users');
    client.release(); // ❌ Only releases on success
    return result.rows;
  } catch (error) {
    throw error; // ❌ Connection leaked!
  }
}

// After (FIXED)
async getUsers() {
  const client = await pool.connect();
  try {
    const result = await client.query('SELECT * FROM users');
    return result.rows;
  } catch (error) {
    throw error;
  } finally {
    client.release(); // ✅ Always releases
  }
}

test('releases connection on error', async () => {
  const initialConnections = await getActiveConnections();
  
  // Force an error
  await expect(getUsers({ invalid: true })).rejects.toThrow();
  
  // Verify connection was released
  const finalConnections = await getActiveConnections();
  expect(finalConnections).toBe(initialConnections);
});

### Use Case 2: "Works Locally, Fails in Production"

Error: JWT_SECRET is not defined
  at generateToken (auth.ts:23)

// src/config/env.ts
function validateEnv() {
  const required = ['JWT_SECRET', 'DATABASE_URL'];
  const missing = required.filter(key => !process.env[key]);
  
  if (missing.length > 0) {
    throw new Error(`Missing required env vars: ${missing.join(', ')}`);
  }
}

validateEnv(); // Run at startup

### Use Case 3: Memory Leak Investigation

class DataService {
  async fetchData() {
    eventBus.on('data-update', this.handleUpdate); // ❌ LEAK!
    // ...
  }
}

class DataService {
  async fetchData() {
    const handler = this.handleUpdate.bind(this);
    eventBus.on('data-update', handler);
    
    try {
      // ... fetch logic
    } finally {
      eventBus.off('data-update', handler); // ✅ Cleanup
    }
  }
}

test('cleans up event listeners', async () => {
  const initialListeners = eventBus.listenerCount('data-update');
  
  await dataService.fetchData();
  
  const finalListeners = eventBus.listenerCount('data-update');
  expect(finalListeners).toBe(initialListeners);
});

## Tool Selection

### Browser Issues

| Need | Tool |
|------|------|
| See network requests | Network tab |
| Inspect DOM state | Elements tab |
| Debug JavaScript | Sources tab + breakpoints |
| Performance analysis | Performance tab |
| Memory investigation | Memory tab |

### Backend Issues

| Need | Tool |
|------|------|
| See request flow | Logging |
| Debug step-by-step | Debugger (--inspect) |
| Find slow queries | Query logging, EXPLAIN |
| Memory issues | Heap snapshots |
| Find regression | git bisect |

## Anti-Patterns

| ❌ Anti-Pattern | ✅ Correct Approach |
|-----------------|---------------------|
| Random changes hoping to fix | Systematic investigation |
| Ignoring stack traces | Read every line carefully |
| "Works on my machine" | Reproduce in same environment |
| Fixing symptoms only | Find and fix root cause |
| No regression test | Always add test for the bug |
| Multiple changes at once | One change, then verify |
| Guessing without data | Profile and measure first |

## Review Checklist

### Before Starting
- [ ] Can reproduce consistently
- [ ] Have error message/stack trace
- [ ] Know expected behavior
- [ ] Checked recent changes

### During Investigation
- [ ] Added strategic logging
- [ ] Traced data flow
- [ ] Used debugger/breakpoints
- [ ] Checked relevant logs

### After Fix
- [ ] Root cause documented
- [ ] Fix verified
- [ ] Regression test added
- [ ] Similar code checked
- [ ] Debug logging removed

## Best Practices

<CardGroup cols={2}>
  <Card title="Reproduce First" icon="repeat">
    Can't fix what you can't consistently reproduce
  </Card>
  <Card title="Follow Evidence" icon="chart-line">
    Stack traces and logs over assumptions
  </Card>
  <Card title="Root Cause" icon="bullseye">
    Use 5 Whys to find the real problem
  </Card>
  <Card title="Prevent Regression" icon="shield">
    Every bug needs a test
  </Card>
</CardGroup>

## Automatic Selection Triggers

Debugger is automatically selected when:
- User mentions "bug", "error", "crash", "not working", "broken"
- Investigation is clearly needed
- User asks to "investigate", "fix", "debug"
- Production issues mentioned

## Related Agents

<CardGroup cols={2}>
  <Card title="Test Engineer" icon="vial" href="/agents/test-engineer">
    Adds regression tests for fixed bugs
  </Card>
  <Card title="Performance Optimizer" icon="gauge-high" href="/agents/performance-optimizer">
    Helps with performance-related bugs
  </Card>
</CardGroup>