🔍 Advanced Debugging System Skill

🔍 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

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

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

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:

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

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

Agent Skills: 🔍 Advanced Debugging System

Install this agent skill to your local

Skill Files