debugging-first

Debugging First

RULE: Use debugging tools BEFORE examining or modifying code when investigating issues.

The Principle

When something isn't working, gather evidence FIRST before making changes. Debugging tools give you facts; guessing wastes time.

Debugging Tool Priority

1. Console/Logs (First Priority)

DO:

• Check console output for errors
• Look at warning messages
• Review log files
• Check for stack traces
• Note the exact error message and location

# Browser console (via Puppeteer evaluate)
mcp__puppeteer__puppeteer_evaluate({ script: "console.log('checking...')" })

# Server logs
tail -f logs/app.log

# Build output
npm run build 2>&1 | head -50

2. Network Requests (Second Priority)

DO:

• Check API call responses
• Verify request payloads
• Look for failed requests (4xx, 5xx)
• Check response status codes
• Examine request/response headers

# Browser network (via Puppeteer evaluate)
mcp__puppeteer__puppeteer_evaluate({ script: "performance.getEntriesByType('resource')" })

# CLI testing
curl -v [endpoint]

# Check for CORS issues
# Look for preflight failures

3. Application State (Third Priority)

DO:

• Inspect current state values
• Check what data is loaded
• Verify props/arguments received
• Look at environment variables
• Check localStorage/sessionStorage

4. Code Examination (Last Priority)

Only AFTER gathering evidence from above:

• Read the relevant code
• Trace the execution path
• Check the logic
• Verify assumptions

The Debugging Process

Step 1: Gather Evidence

User: "The login isn't working"

Agent (CORRECT approach):
1. Check console logs for errors
2. Check network tab for API calls
3. Check what error message (if any) is shown
4. Check if user is redirected or stays on page
5. NOW look at the code with context

Step 2: Analyze Before Acting

With debugging evidence in hand:

• Identify the actual failure point
• Understand the error cause
• Form a hypothesis
• Verify hypothesis before fixing