Bug Hunting Workflow - Cursor IDE

Scenario

Production is down. Users report that checkout fails intermittently with a vague “Transaction failed” error. It works fine in development, happens only under load, and started after last week’s deployment. The error rate is 15% and growing. Your CEO is asking for updates every 30 minutes.

Learning Objectives

By completing this lesson, you’ll master:

• Systematic debugging methodology with AI
• Root cause analysis techniques
• Production debugging strategies
• Performance profiling with AI assistance
• Creating reproducible test cases
• Implementing permanent fixes with monitoring

Prerequisites

• Basic debugging experience
• Understanding of distributed systems
• Familiarity with logging and monitoring
• Access to production logs (simulated)

The Challenge

Debug a complex production issue involving:

• Intermittent failures (Heisenbugs)
• Race conditions
• Performance degradation
• Multiple service interactions
• Incomplete error messages
• Time pressure

Uwaga

Production debugging requires careful analysis. Hasty fixes often make things worse. Use AI to systematically investigate before implementing solutions.

Guided Implementation

Phase 1: Initial Investigation

1. Gather Symptoms

Start with Ask mode to analyze available information:

"Help me create a systematic debugging plan for:
- Error: 'Transaction failed' during checkout
- Frequency: 15% of transactions
- Started: After deployment on [date]
- Pattern: Only under load, works in dev
What information should I gather first?"

2. Analyze Error Logs

@logs/production-errors.log
"Analyze these error logs:
- Find patterns in failed transactions
- Identify common characteristics
- Look for timing patterns
- Check for correlated errors
- Extract unique error signatures"

3. Review Recent Changes

@git log --since="1 week ago" --oneline
"Review recent commits that could cause:
- Race conditions
- Performance issues
- Database deadlocks
- Payment processing changes
Focus on checkout and payment flows"

Phase 2: Hypothesis Formation

1. Generate Hypotheses

Switch to Agent mode:

@logs/errors.log @src/checkout @src/payment
"Based on the symptoms and code, generate hypotheses for:
- Why it only fails under load
- Why error message is generic
- Possible race conditions
- Database connection issues
Rank by probability"

2. Create Investigation Plan

"Create a detailed investigation plan for top 3 hypotheses:
1. What to look for in logs
2. Queries to run on database
3. Metrics to check
4. Code paths to trace
5. Tests to write"

3. Trace Transaction Flow

@src/checkout/service.js @src/payment/processor.js
"Trace a complete checkout transaction:
- Create sequence diagram
- Identify all external calls
- Mark async operations
- Find potential race conditions
- Note error handling gaps"

Phase 3: Reproduction

1. Create Load Test

"Create a load test to reproduce the issue:
- Simulate production traffic patterns
- Include concurrent checkouts
- Vary payment amounts and methods
- Add network latency
- Monitor for the exact error"

Example load test:

load-test.js

import { check } from 'k6';
import http from 'k6/http';

export const options = {
  stages: [
    { duration: '30s', target: 100 },
    { duration: '1m', target: 200 },
    { duration: '30s', target: 0 },
  ],
  thresholds: {
    http_req_failed: ['rate < 0.1'], // Less than 10% errors
    http_req_duration: ['p(95) < 500'], // 95% under 500ms
  },
};

export default function() {
  const payload = JSON.stringify({
    items: [{ id: 1, quantity: 2 }],
    payment: {
      method: 'credit_card',
      amount: Math.random() * 1000,
    },
  });

  const response = http.post(
    'http://localhost:3000/api/checkout',
    payload,
    { headers: { 'Content-Type': 'application/json' } }
  );

  check(response, {
    'status is 200': (r) => r.status === 200,
    'no transaction error': (r) => !r.body.includes('Transaction failed'),
  });
}

2. Add Detailed Logging

@src/checkout/service.js
"Add comprehensive debug logging:
- Transaction start/end times
- Database query durations
- External API call times
- Lock acquisition/release
- Connection pool stats
Use structured logging with correlation IDs"

3. Create Minimal Reproduction

"Create minimal code to reproduce the issue:
- Remove unnecessary complexity
- Focus on the failing path
- Make it deterministic if possible
- Add timing controls
- Document reproduction steps"

Phase 4: Root Cause Analysis

1. Analyze Timing Issues

@logs/debug-trace.log
"Analyze transaction timings:
- Find operations taking too long
- Identify concurrent operations
- Look for lock contention
- Check timeout configurations
- Correlate with failures"

2. Database Investigation

-- AI generates diagnostic queries
"Generate SQL queries to investigate:
- Deadlocks in the payment table
- Long-running transactions
- Connection pool exhaustion
- Lock wait timeouts
- Index usage statistics"

3. Identify Root Cause

Based on investigation, AI helps identify:

// Root cause found: Database connection pool exhaustion
// Old code:
async function processPayment(paymentData) {
  const conn = await db.getConnection();
  try {
    await conn.beginTransaction();

    // Bug: Connection not released on early return
    if (!validatePayment(paymentData)) {
      return { error: 'Transaction failed' }; // Connection leaked!
    }

    const result = await conn.query('INSERT INTO payments...');
    await conn.commit();
    return result;
  } catch (error) {
    await conn.rollback();
    throw error;
  } finally {
    conn.release(); // Not reached on validation failure
  }
}

Phase 5: Fix Implementation

1. Implement Fix

@src/payment/processor.js
"Fix the connection leak issue:
- Ensure connections always released
- Add connection pool monitoring
- Improve error messages
- Add circuit breaker pattern
- Include correlation IDs"

Fixed code:

async function processPayment(paymentData) {
  const conn = await db.getConnection();
  try {
    // Validate before transaction
    if (!validatePayment(paymentData)) {
      return {
        error: 'Payment validation failed',
        details: getValidationErrors(paymentData),
        correlationId: generateCorrelationId()
      };
    }

    await conn.beginTransaction();

    const result = await conn.query('INSERT INTO payments...', paymentData);
    await conn.commit();

    logger.info('Payment processed successfully', {
      paymentId: result.insertId,
      correlationId: paymentData.correlationId
    });

    return { success: true, paymentId: result.insertId };
  } catch (error) {
    await conn.rollback();
    logger.error('Payment processing failed', {
      error: error.message,
      stack: error.stack,
      paymentData,
      correlationId: paymentData.correlationId
    });
    throw new PaymentError('Transaction failed', error);
  } finally {
    // Always release connection
    conn.release();
  }
}

2. Add Monitoring

"Add comprehensive monitoring:
- Connection pool metrics
- Transaction duration histogram
- Error rate by type
- Queue depth monitoring
- Alert thresholds"

3. Create Tests

@src/payment/processor.test.js
"Create tests for the bug:
- Test connection leak scenario
- Test under concurrent load
- Test error handling
- Test monitoring metrics
- Test circuit breaker"

Key Techniques Demonstrated

Technique 1: Systematic Debugging Process

Follow this proven pattern:

graph TD A[Gather Symptoms] --> B[Form Hypotheses] B --> C[Create Reproduction] C --> D[Root Cause Analysis] D --> E[Implement Fix] E --> F[Verify & Monitor] F --> G[Document Learning]

Technique 2: Binary Search Debugging

Narrow down the problem:

// Start wide
"The checkout process is failing"

// Narrow to subsystem
"The payment processing is failing"

// Narrow to specific operation
"Database connections are leaking during validation"

// Find exact line
"Line 47: early return without connection release"

Technique 3: Time Travel Debugging

Use git bisect with AI:

# AI helps create test script
@src/checkout
"Create a script that returns 0 if checkout works, 1 if it fails"

# Use git bisect
git bisect start
git bisect bad HEAD
git bisect good abc123
git bisect run ./test-checkout.sh

Common Debugging Scenarios

Race Conditions

"Analyze this code for race conditions:
- Identify shared resources
- Find missing synchronization
- Look for check-then-act patterns
- Suggest fixes with proper locking"

Memory Leaks

"Help me find memory leaks:
- Analyze heap dumps
- Find circular references
- Identify unclosed resources
- Suggest cleanup patterns"

Performance Issues

"Profile this slow operation:
- Add timing measurements
- Find N+1 queries
- Identify CPU bottlenecks
- Suggest optimizations"

Extended Challenge

Level up your debugging skills:

1. Distributed Tracing

   • Implement OpenTelemetry
   • Trace across microservices
   • Correlate logs and metrics
   • Visualize request flow

2. Chaos Engineering

   • Inject controlled failures
   • Test resilience patterns
   • Automate failure recovery
   • Document failure modes

3. AI-Powered Monitoring

   • Anomaly detection
   • Predictive alerts
   • Auto-remediation
   • Root cause suggestions

Debugging Metrics

Track your debugging effectiveness:

• ⏱️ Mean Time to Detection (MTTD): < 5 minutes
• 🔍 Mean Time to Identification (MTTI): < 30 minutes
• 🔧 Mean Time to Resolution (MTTR): < 2 hours
• 🎯 First Fix Success Rate: > 90%
• 📊 Recurrence Rate: < 5%

Real-World War Stories

The 2AM Database Deadlock

“Used Cursor to analyze 50K lines of logs in minutes, found the circular dependency that only occurred when orders exceeded $9,999.99”

The Phantom Memory Leak

“AI identified a WebSocket event listener that wasn’t cleaned up on reconnection, causing 10MB/hour memory growth”

The Monday Morning Surge

“Discovered cache stampede pattern when all user sessions expired simultaneously at week start”

Debugging Toolkit

Essential tools integrated with Cursor:

.cursor/debug-toolkit.md

## Quick Commands

### Analyze Logs
@logs/production.log "Find anomalies in the last hour"

### Check Performance
@src/slow-endpoint.js "Profile and find bottlenecks"

### Trace Execution
@src "Trace execution path for user ID 12345"

### Find Similar Issues
@git log --grep="Transaction failed" "Show how similar issues were fixed"

Key Takeaways

1. Be Systematic: Random changes make debugging harder
2. Reproduce First: Can’t fix what you can’t reproduce
3. Measure Everything: Data beats guesswork
4. Fix Root Causes: Don’t just patch symptoms
5. Document Findings: Today’s bug is tomorrow’s knowledge

Next Steps

You’ve mastered systematic debugging. Ready for more?

Build Debug Tools

Create custom debugging utilities for your stack

Teach Others

Run a debugging workshop for your team

Contribute

Share your debugging patterns with the community

Continue to API Integration →

Wskazówka

Start a debugging journal. Document each interesting bug: symptoms, investigation process, root cause, and fix. This becomes invaluable reference material and can train AI on your specific patterns.