tomevault-io 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
- [Step to verify fix works]
- [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
| Error | Likely Cause | Investigation |
|---|---|---|
| Property 'x' does not exist | Type changed, typo | Check interface definition |
| Cannot find module | Missing import, path error | Check tsconfig paths |
| Type 'X' is not assignable | Type mismatch | Check both type definitions |
| Argument of type 'X' | Function signature changed | Check function definition |
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.]
| Error | Likely Cause | Investigation |
|---|---|---|
| Unknown field | Schema changed after last code-gen | Re-run schema generation |
| Invalid model call | Model renamed or removed | Check the schema file |
| Foreign key constraint | Data integrity issue | Check relation definitions |
Runtime Errors
| Error | Likely Cause | Investigation |
|---|---|---|
| Cannot read property of undefined | Null reference | Add null checks |
| Maximum call stack exceeded | Infinite recursion | Check recursive calls |
| Connection refused | Service down | Check infrastructure |
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
---
> Source: [mnzralee/claude-multi-agent-architecture](https://github.com/mnzralee/claude-multi-agent-architecture) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-25 -->