advanced-debugging

最先进的调试代理,具有假设驱动分析、自动代码检测、git工作树隔离和浏览器自动化功能。在调试错误、堆栈跟踪、意外行为、性能问题、失败的测试、竞态条件或难以重现的错误时使用。

📖 中文导读:最先进的调试代理,具有假设驱动分析、自动代码检测、git工作树隔离和浏览器自动化功能。在调试错误、堆栈跟踪、意外行为、性能问题、失败的测试、竞态条件或难以重现的错误时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: advanced-debugging description: State-of-the-art debugging agent with hypothesis-driven analysis, automatic code instrumentation, git worktree isolation, and browser automation. Use when debugging errors, stack traces, unexpected behavior, performance issues, failed tests, race conditions, or hard-to-reproduce bugs. metadata: author: coachone version: "2.0" compatibility: Requires git, Node.js 18+. Optional Playwright for browser automation. allowed-tools: Bash(git:) Bash(grep:) Bash(find:*) Read Write

🔍 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