Systematic Debugging Skill

A structured approach to debugging that ensures thorough diagnosis before attempting fixes. The discipline is stack-agnostic and applies equally to TypeScript/Node, Python, Go, or any other language and runtime.

When to Use This Skill

Use this skill when:

• An implementation agent fails with an error
• Tests are failing unexpectedly
• Runtime behavior does not match expectations
• Build or compilation errors occur

The Debugging Protocol

Phase 1: Error Capture

DO NOT attempt to fix anything until you understand:

## Error Analysis

### Exact Error

[paste exact error message]

### Error Location
- File: [path/to/file]
- Line: [line number]
- Function: [function name]

### Error Type
- [ ] Compilation error
- [ ] Runtime error
- [ ] Test failure
- [ ] Build failure
- [ ] Infrastructure error

### Trigger
What action caused this error?

Phase 2: Context Gathering

Before diagnosing, gather context:

# Recent changes
git log --oneline -10

# Changes in affected file
git diff HEAD~5 -- [file_path]

# Related files
grep -r "[error_pattern]" --include="*.ts"

Phase 3: Root Cause Analysis

Use the "5 Whys" technique:

## Root Cause Analysis

1. **Why did the error occur?**
   [Direct cause, e.g., "Property 'x' does not exist on type 'Y'"]

2. **Why does property 'x' not exist?**
   [e.g., "The type definition was changed"]

3. **Why was the type definition changed?**
   [e.g., "A schema migration removed the field"]

4. **Why wasn't the code updated?**
   [e.g., "The dependent service wasn't identified"]

5. **Why wasn't it identified?**
   [ROOT CAUSE, e.g., "No automated dependency check"]

Phase 4: Impact Assessment

## Impact Assessment

### Direct Impact
- [File/component directly affected]

### Cascade Impact
- [Other components that depend on the affected code]

### Test Impact
- [Tests that will fail due to this issue]

### User Impact
- [How this affects end users if deployed]

Phase 5: Fix Strategy

Only after completing phases 1-4:

## Fix Strategy

### Approach
[Description of the fix approach]

### Files to Modify
1. `path/to/file1.ts` - [what to change]
2. `path/to/file2.ts` - [what to change]

### Code Changes
```typescript
// BEFORE
[problematic code]

// AFTER
[fixed code]

Verification Steps

1. [Step to verify fix works]
2. [Step to verify no regressions]

### Phase 6: Prevention

```markdown
## Prevention

### Why This Happened
[Brief explanation]

### How to Prevent
- [ ] Add test case for this scenario
- [ ] Add type check
- [ ] Add documentation
- [ ] Update dependency tracking

Common Error Patterns

TypeScript Compilation Errors

ORM / Data-Layer Errors

These examples use a generic ORM pattern. [CUSTOMIZE: replace with your ORM's error vocabulary, e.g., Drizzle, TypeORM, SQLAlchemy, or similar.]

Runtime Errors

Debugger Agent Output Format

## Debugging Report

### Error Summary
[One sentence description]

### Root Cause
[Identified root cause from 5 Whys analysis]

### Affected Components
| Component | Impact Level | Fix Required |
|-----------|--------------|--------------|
| [file/service] | HIGH/MED/LOW | Yes/No |

### Recommended Fix

#### Files to Modify
1. `[path]` - [change description]

#### Code Changes
```typescript
// File: [path]
// Line: [n]

// Replace:
[old code]

// With:
[new code]

Verification

[verification commands]

Prevention

[How to prevent this in future]

## Integration with Multi-Agent System

When called by the supervisor agent, the debugger agent receives an error payload and returns a structured diagnosis. [CUSTOMIZE: adjust field names to match your work-package and agent naming conventions.]

supervisor -> debugger: { "error": "[error message]", "context": { "workPackage": "WP-01", "agent": "impl-agent", "files": ["path/to/file.ts"], "recentChanges": "[git diff output]" } }

debugger -> supervisor: { "status": "DIAGNOSED", "rootCause": "[explanation]", "fix": { "files": ["path/to/file.ts"], "changes": "[code changes]", "verification": ["npx tsc --noEmit"] }, "prevention": "[suggestion]" }

## Anti-Patterns

### DON'T:
- Jump to fixing without understanding the error
- Make multiple changes at once
- Assume the error message is the root cause
- Skip verification after fix
- Ignore prevention analysis

### DO:
- Follow the phases in order
- Isolate the exact error location
- Understand the full impact
- Fix one thing at a time
- Verify thoroughly
- Document for future reference