# advanced-debugging

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

- Author: g97iulio1609
- Repository: g97iulio1609/vscode-agent-skills
- Version: 20251222160051
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/g97iulio1609/vscode-agent-skills
- Web: https://mule.run/skillshub/@@g97iulio1609/vscode-agent-skills~advanced-debugging:20251222160051

---

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

```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

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](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](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](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:
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