Debugging Detective | Bootspring Docs

The Debugging Detective agent specializes in finding and fixing bugs, analyzing errors, and troubleshooting issues.

Expertise Areas#

Error Analysis - Stack traces, error messages, logs
Root Cause Analysis - Finding the source of issues
Debugging Tools - DevTools, debuggers, profilers
Performance Issues - Memory leaks, slow queries
Integration Bugs - API issues, third-party problems
Reproduction - Creating minimal test cases
Fix Strategies - Patches, workarounds, proper fixes

Usage Examples#

Error Analysis#

Use the debugging-detective agent to analyze this error:
TypeError: Cannot read properties of undefined (reading 'map')
at UserList (UserList.tsx:15:23)

Response includes:

Error explanation
Likely causes
Code investigation points
Fix recommendations

Performance Investigation#

Use the debugging-detective agent to investigate why our API is slow.

Response includes:

Investigation steps
Profiling recommendations
Common causes
Optimization suggestions

Bug Hunting#

Use the debugging-detective agent to find why user sessions are randomly expiring.

Response includes:

Systematic investigation plan
Likely causes
Logging recommendations
Verification steps

Debugging Process#

1. Understand the Problem#

Questions to answer:
- What is the expected behavior?
- What is the actual behavior?
- When did it start happening?
- Is it reproducible?
- What changed recently?

2. Gather Evidence#

Evidence sources:
- Error messages and stack traces
- Application logs
- Network requests/responses
- Database queries
- User reports
- Git history

3. Form Hypotheses#

Based on evidence, list possible causes:
1. Most likely: [hypothesis]
2. Second likely: [hypothesis]
3. Less likely but possible: [hypothesis]

4. Test Hypotheses#

For each hypothesis:
1. Create a test case
2. Add logging/debugging
3. Reproduce the issue
4. Verify the cause

5. Fix and Verify#

Fix approach:
1. Implement the fix
2. Write regression test
3. Test the fix
4. Review for side effects
5. Deploy and monitor

Common Bug Patterns#

Null/Undefined Errors#

// Problem
const name = user.profile.name; // user.profile is undefined

// Fix 1: Optional chaining
const name = user?.profile?.name;

// Fix 2: Default values
const name = user?.profile?.name ?? 'Unknown';

// Fix 3: Guard clause
if (!user?.profile) {
  throw new Error('User profile not loaded');
}
const name = user.profile.name;

Race Conditions#

// Problem: State update after unmount
useEffect(() => {
  fetchData().then(setData); // Component might unmount
}, []);

// Fix: Cleanup function
useEffect(() => {
  let cancelled = false;

  fetchData().then(data => {
    if (!cancelled) setData(data);
  });

  return () => { cancelled = true; };
}, []);

Memory Leaks#

// Problem: Event listener not cleaned up
useEffect(() => {
  window.addEventListener('resize', handleResize);
}, []); // Missing cleanup!

// Fix: Return cleanup function
useEffect(() => {
  window.addEventListener('resize', handleResize);
  return () => window.removeEventListener('resize', handleResize);
}, []);

Async/Await Errors#

// Problem: Unhandled promise rejection
async function fetchUser(id: string) {
  const response = await fetch(`/api/users/${id}`);
  return response.json(); // What if response is not OK?
}

// Fix: Proper error handling
async function fetchUser(id: string) {
  const response = await fetch(`/api/users/${id}`);

  if (!response.ok) {
    throw new Error(`Failed to fetch user: ${response.status}`);
  }

  return response.json();
}

Debugging Tools#

Browser DevTools#

// Console methods
console.log('Basic log');
console.table(arrayOfObjects);
console.time('operation');
// ... operation
console.timeEnd('operation');
console.trace('Call stack');

// Debugger statement
function problematicFunction() {
  debugger; // Execution pauses here
  // ... code to debug
}

Node.js Debugging#

# Inspect mode
node --inspect app.js

# Break on first line
node --inspect-brk app.js

# Debug tests
node --inspect-brk node_modules/.bin/jest --runInBand

Network Debugging#

// Log all fetch requests
const originalFetch = window.fetch;
window.fetch = async (...args) => {
  console.log('Fetch:', args);
  const response = await originalFetch(...args);
  console.log('Response:', response.status);
  return response;
};

Logging Strategies#

Structured Logging#

import pino from 'pino';

const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
});

// Good logging
logger.info({ userId, action: 'login' }, 'User logged in');
logger.error({ err, userId, endpoint }, 'API request failed');

// Include context
logger.child({ requestId, userId }).info('Processing request');

Debug Points#

// Strategic logging points
async function processOrder(order: Order) {
  logger.info({ orderId: order.id }, 'Starting order processing');

  try {
    const validated = await validateOrder(order);
    logger.debug({ orderId: order.id }, 'Order validated');

    const payment = await processPayment(validated);
    logger.debug({ orderId: order.id, paymentId: payment.id }, 'Payment processed');

    const result = await fulfillOrder(validated, payment);
    logger.info({ orderId: order.id }, 'Order completed');

    return result;
  } catch (error) {
    logger.error({ err: error, orderId: order.id }, 'Order processing failed');
    throw error;
  }
}

Sample Prompts#

Task	Prompt
Error analysis	"Why am I getting 'Maximum update depth exceeded'?"
Performance	"Debug why this component re-renders constantly"
Async issues	"Find the race condition in this checkout flow"
Memory leak	"Investigate memory growth in this long-running process"
Integration	"Debug why webhook payloads are malformed"

Configuration#

// bootspring.config.js
module.exports = {
  agents: {
    customInstructions: {
      'debugging-detective': `
        - Ask clarifying questions
        - Start with the most likely cause
        - Suggest adding strategic logging
        - Consider edge cases
        - Recommend regression tests
      `,
    },
  },
};

Testing Expert - Regression tests
Performance Expert - Performance issues
Backend Expert - Server-side debugging