debugging-and-error-recovery

Debugging and Error Recovery

Overview

Debug systematically, not randomly. The most common debugging mistake is jumping to a fix before understanding the problem. Premature fixes mask symptoms, introduce new bugs, and waste time. The correct approach: reproduce the bug, read the error carefully, form a hypothesis, verify it, fix the root cause, confirm the fix.

When to Use

• Encountering an error message or exception
• Tests are failing unexpectedly
• A feature works in some cases but not others
• Recent changes broke something that was working
• Runtime behavior doesn't match what the code suggests

The Debugging Protocol

Step 1: Read the Error (Don't Skim)

The error message contains the answer most of the time. Read it in full:

READ THE ERROR:
→ What is the error type? (TypeError, ReferenceError, 404, etc.)
→ What is the exact message?
→ What file and line number?
→ What is the full stack trace (not just the first line)?
→ Is there a "caused by" or inner exception?

Use code_execution_tool to capture full error output:

# Run with full stack trace
node --stack-trace-limit=50 script.js 2>&1

# Python with full traceback
python -m traceback script.py 2>&1

# Capture test failures in full
npx vitest run --reporter=verbose 2>&1

Step 2: Reproduce Reliably

Before fixing, make the bug reproducible on demand:

REPRODUCTION QUESTIONS:
- Can I trigger this consistently?
- What exact inputs/conditions trigger it?
- Does it happen in isolation, or only with other code?
- Does it happen in test environment? Production? Both?
- Did it ever work? If so, what changed?

If you can't reproduce it, you can't verify when it's fixed. Use code_execution_tool to write a minimal reproduction:

// Minimal reproduction — remove everything not needed to trigger the bug
const { processTask } = require('./task-processor');

const task = { id: '123', title: '', status: 'pending' };
const result = processTask(task);
console.log(result); // Should trigger the bug