🔍 Advanced Debugging System

A systematic, hypothesis-driven debugging approach with automatic instrumentation and isolated testing capabilities.

Quick Reference

Task	Command
Instrument file	Run scripts/instrument.ts <file>
Analyze logs	Run scripts/analyze-logs.ts <logfile>
Create worktree	Run scripts/worktree.ts create <name>
Cleanup worktree	Run scripts/worktree.ts cleanup <name>
Generate hypothesis report	Follow "Hypothesis Generation" section

Core Methodology

Phase 0: Hypothesis Generation (MANDATORY FIRST STEP)

NEVER attempt fixes before generating at least 3 hypotheses.

## 🔮 Bug Hypotheses

### Hypothesis 1: [Name] - Probability: [High/Medium/Low]
- **Suspected Cause**: [specific description]
- **Evidence Needed**: [what logs/tests to add]
- **Verification Method**: [how to confirm]

### Hypothesis 2: [Name] - Probability: [High/Medium/Low]
- **Suspected Cause**: [specific description]
- **Evidence Needed**: [what logs/tests to add]
- **Verification Method**: [how to confirm]

### Hypothesis 3: [Name] - Probability: [High/Medium/Low]
- **Suspected Cause**: [specific description]
- **Evidence Needed**: [what logs/tests to add]
- **Verification Method**: [how to confirm]

Phase 1: Information Gathering

1. Read the full error - Extract error type, message, stack trace
2. Identify error category:
   • TYPE_ERROR - TypeScript/type issues
   • RUNTIME_ERROR - Execution failures
   • NETWORK_ERROR - API/fetch issues
   • DATABASE_ERROR - Prisma/SQL issues
   • BUILD_ERROR - Compilation/bundle issues
   • STATE_ERROR - React state/hydration issues

Phase 2: Stack Trace Analysis

Error Analysis Template:
┌─────────────────────────────────────────────┐
│ ERROR: [error message]                       │
├─────────────────────────────────────────────┤
│ Type: [error type]                          │
│ First Project File: [file:line]             │
│ Call Chain: fn1 → fn2 → fn3                 │
│ Suspected Origin: [description]             │
└─────────────────────────────────────────────┘

Phase 3: Automatic Instrumentation

See INSTRUMENTATION.md for detailed patterns.

Quick instrumentation markers:

// 🔍 DEBUG markers for easy identification and cleanup
console.log('🔍 DEBUG [LOCATION]:', { timestamp: new Date().toISOString(), /* context */ });

Cleanup pattern:

grep -rn "🔍 DEBUG" --include="*.ts" --include="*.tsx" src/

Phase 4: Isolated Testing with Git Worktrees

For complex bugs, test hypotheses in parallel:

# Create isolated environment
git worktree add ../debug-hypothesis-1 -b debug/h1-[description]

# After finding solution
git worktree remove ../debug-hypothesis-1
git branch -D debug/h1-[description]

See WORKTREES.md for multi-hypothesis workflows.

Phase 5: Fix-Verify-Document Cycle

1. Minimal Fix: Change only what's necessary
2. Verify: Reproduce original scenario
3. Regression Test: Ensure no side effects
4. Document: Comment non-obvious fixes

Error Pattern Quick Reference

See references/ERROR_PATTERNS.md for comprehensive patterns.

Common Next.js Patterns

Error	Likely Cause	Quick Fix
Hydration mismatch	Server/client content differs	Add suppressHydrationWarning or fix data
Cannot read property of undefined	Missing null check	Add optional chaining ?.
Module not found	Import path issue	Check tsconfig paths
NEXT_REDIRECT	Redirect in wrong context	Use redirect() only in Server Components

Common Prisma Patterns

Error	Likely Cause	Quick Fix
P2002	Unique constraint violation	Check existing data
P2025	Record not found	Verify ID exists
Connection refused	DB not running	Check DATABASE_URL

Feedback Loop Integration

For UI bugs, use browser automation:

// Playwright verification loop
{
  action: 'navigate', url: 'http://localhost:3000/[page]'
}
{
  action: 'console_messages', errorsOnly: true
}
{
  action: 'screenshot', fullPage: true
}

Output Template

When resolving a bug, ALWAYS provide:

## 🐛 Debug Report

### 🔴 Problem Identified
[Clear description of the bug]

### 🔍 Root Cause
[Main cause with evidence]

### ✅ Solution Applied
[Fix with explanation]

### 🧪 Verification
[How to confirm fix works]

### 🛡️ Prevention
[How to avoid in future]

Escalation Criteria

If after systematic analysis no solution is found:

1. Summarize attempts made
2. List remaining hypotheses
3. Suggest next investigative steps
4. Request additional context

Safety Constraints

• ❌ NO production data modification without confirmation
• ❌ NO destructive commands (rm -rf, DROP DATABASE) without confirmation
• ❌ NO ignoring warnings that indicate future problems
• ✅ ALWAYS ask confirmation for invasive fixes