🔍 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.

markdown

## 🔮 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

•Read the full error - Extract error type, message, stack trace
•
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

code

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:

typescript

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

Cleanup pattern:

bash

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

Phase 4: Isolated Testing with Git Worktrees

For complex bugs, test hypotheses in parallel:

bash

# 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

•Minimal Fix: Change only what's necessary
•Verify: Reproduce original scenario
•Regression Test: Ensure no side effects
•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:

typescript

// 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:

markdown

## 🐛 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:

•Summarize attempts made
•List remaining hypotheses
•Suggest next investigative steps
•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