Debug with AI

Structured debugging workflows using AI as your debugging partner.

When to Use

Code throws an error you don't understand
Feature works sometimes but not always
Unexpected behavior that's hard to trace
Performance issues or memory leaks
Complex stack traces to decipher

The Debugging Framework

┌───────────────────────────────────────────┐
│ 1. REPRODUCE - Can you trigger it?        │
├───────────────────────────────────────────┤
│ 2. ISOLATE - Where exactly is the issue?  │
├───────────────────────────────────────────┤
│ 3. UNDERSTAND - Why does it happen?       │
├───────────────────────────────────────────┤
│ 4. FIX - Make minimal change to resolve   │
├───────────────────────────────────────────┤
│ 5. VERIFY - Confirm fix, add test         │
└───────────────────────────────────────────┘

Step 1: Reproduce

Before asking AI for help, gather information:

Collect This Information

## Bug Report

**What I expected:**
[Expected behavior]

**What actually happened:**
[Actual behavior]

**Error message (if any):**

[Full error message and stack trace]


**Steps to reproduce:**
1. [Step 1]
2. [Step 2]
3. [Step 3]

**Environment:**
- Node/Browser version:
- OS:
- Relevant packages:

**Code involved:**
```[paste relevant code]```

**What I've already tried:**
- [Attempt 1]
- [Attempt 2]

Step 2: Isolate

Binary Search for Bugs

If you don't know where the bug is:

Comment out half the code
Does bug still occur?
- Yes → Bug is in remaining code
- No → Bug is in commented code
Repeat with that half

AI Prompt for Isolation

I have a bug somewhere in this code flow:

1. Function A calls Function B
2. Function B processes data and calls Function C
3. Function C returns result

The bug manifests as [description].

Here's the code:
```[paste relevant functions]```

Help me identify which function is most likely causing the issue
and what I should check first.

Step 3: Understand with AI

For Error Messages

Explain this error and likely causes:

TypeError: Cannot read properties of undefined (reading 'map') at processItems (processor.js:45:12) at async handleRequest (handler.js:23:5)


Code at processor.js:45:
```[paste surrounding code]```

What are the most likely causes and how do I fix them?

For Unexpected Behavior

This code doesn't behave as expected:

```[paste code]```

**Expected:** When input is X, output should be Y
**Actual:** Output is Z

Walk me through the code execution step by step
and identify where the logic diverges from my expectation.

For Intermittent Bugs

This bug only happens sometimes:

```[paste code]```

**Symptoms:** [description]
**Frequency:** About 1 in 10 times
**Conditions:** Seems more common when [observation]

What could cause intermittent failures? Consider:
- Race conditions
- Timing issues
- External dependencies
- State management
- Caching

Step 4: Fix

AI Prompt for Fix

I've identified the bug:

**Problem:** [description of root cause]

**Current code:**
```[paste buggy code]```

**Context/constraints:**
- [Any constraints on the fix]
- [Backward compatibility needs]

Provide a minimal fix that:
1. Solves the immediate problem
2. Handles edge cases
3. Doesn't introduce new issues

Fix Quality Checklist

Fixes root cause, not just symptom
Handles related edge cases
Doesn't break existing functionality
Is the minimal necessary change
Is clear and maintainable

Step 5: Verify

Create Regression Test

Generate a test that would have caught this bug:

**Bug:** [description]
**Root cause:** [what was wrong]
**Fix:** [how it was fixed]

**Fixed code:**
```[paste fixed code]```

Create a test that:
1. Fails with the old buggy code
2. Passes with the fix
3. Covers the edge case that caused this

Common Bug Patterns

Null/Undefined Errors

Symptom: Cannot read property 'x' of undefined

AI Prompt:

This code throws "Cannot read property 'items' of undefined":

```javascript
function processOrder(order) {
  return order.items.map(item => item.name);
}

Identify all paths where order or order.items could be undefined and provide defensive code.


### Async/Await Issues

**Symptom:** Function returns Promise instead of value, or undefined

**AI Prompt:**
```markdown
This async code doesn't work as expected:

```javascript
async function getData() {
  const items = fetchItems(); // forgot await
  return items.filter(i => i.active);
}

Error: items.filter is not a function

Find async/await issues and fix them.


### Race Conditions

**Symptom:** Works sometimes, fails other times

**AI Prompt:**
```markdown
This code has a race condition:

```javascript
let cache = null;

async function getData() {
  if (!cache) {
    cache = await fetchData(); // Multiple calls can start fetch
  }
  return cache;
}

Identify the race condition and provide a thread-safe solution.


### State Management Bugs

**Symptom:** UI shows stale data, updates don't reflect

**AI Prompt:**
```markdown
React component doesn't update when it should:

```jsx
function Counter() {
  const [counts, setCounts] = useState({a: 0, b: 0});

  const increment = (key) => {
    counts[key]++; // Mutating state directly!
    setCounts(counts);
  };
}

Identify the state management issue and fix it.


## Debugging Tools Integration

### Console Debugging
```javascript
// Strategic logging
console.log('Function entry:', { input, state });
console.log('After processing:', { result });
console.trace('Call stack'); // Show call stack
console.table(arrayOfObjects); // Tabular display

Browser DevTools

debugger; // Pause execution here

// Conditional breakpoint (in DevTools)
// Right-click line → Add conditional breakpoint
// Condition: user.id === 'problematic-id'

Performance Debugging

console.time('operation');
// ... code to measure
console.timeEnd('operation');

// Or use Performance API
const start = performance.now();
// ... code
console.log(`Took ${performance.now() - start}ms`);

When to Ask AI for Help

Good candidates for AI debugging:

Understanding error messages
Explaining complex stack traces
Identifying patterns in intermittent bugs
Reviewing fix approaches
Generating regression tests

Better to debug manually:

UI layout issues (AI can't see your screen)
Environment-specific issues
Real-time performance profiling
Memory leak investigation (needs tools)

debug-with-ai