🔍 Advanced Debugging System

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

Quick Reference

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

Common Prisma Patterns

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