Systematic error diagnosis and resolution using first-principle analysis. Use when encountering any error message, stack trace, or unexpected behavior. Supports replay functionality to record and reuse solutions.
A first-principle approach to diagnosing and resolving errors across all languages and frameworks.
The 5-step Error Resolution Process:
1. CLASSIFY -> 2. PARSE -> 3. MATCH -> 4. ANALYZE -> 5. RESOLVE
| | | | |
What type? Extract key Known Root cause Fix +
information pattern? analysis Prevent
When you encounter an error:
| Category | Indicators | Common Causes |
|---|---|---|
| Syntax | Parse error, Unexpected token | Typos, missing brackets, invalid syntax |
| Type | TypeError, type mismatch | Wrong data type, null/undefined access |
| Reference | ReferenceError, NameError | Undefined variable, scope issues |
| Runtime | RuntimeError, Exception | Logic errors, invalid operations |
| Network | ECONNREFUSED, timeout, 4xx/5xx | Connection issues, wrong URL, server down |
| Permission | EACCES, PermissionError | File/directory access, sudo needed |
| Dependency | ModuleNotFound, Cannot find module | Missing package, version mismatch |
| Configuration | Config error, env missing | Wrong settings, missing env vars |
| Database | Connection refused, query error | DB down, wrong credentials, bad query |
| Memory | OOM, heap out of memory | Memory leak, large data processing |
Identify the error category by examining:
ENOENT, TypeError)Extract key information:
- Error code: [specific code if any]
- File path: [where the error originated]
- Line number: [exact line if available]
- Function/method: [context of the error]
- Variable/value: [what was involved]
- Stack trace depth: [how deep is the call stack]
Check against known error patterns:
patterns/ directory for language-specific patternsApply the 5 Whys technique:
Error: Cannot read property 'name' of undefined
Why 1? -> user object is undefined
Why 2? -> API call returned null
Why 3? -> User ID doesn't exist in database
Why 4? -> ID was from stale cache
Why 5? -> Cache invalidation not implemented
Root Cause: Missing cache invalidation logic
Generate actionable solution:
When resolving an error, provide:
## Error Diagnosis
**Classification**: [Category] / [Severity] / [Scope]
**Error Signature**:
- Code: [error code]
- Type: [error type]
- Location: [file:line]
## Root Cause
[Explanation of why this error occurred]
**Contributing Factors**:
1. [Factor 1]
2. [Factor 2]
## Solution
### Immediate Fix
[Quick steps to resolve]
### Code Change
[Specific code to add/modify]
### Verification
[How to verify the fix works]
## Prevention
[How to prevent this error in the future]
## Replay Tag
[Unique identifier for this solution - for future reference]
The replay system records successful solutions for future reference.
After resolving an error, record it:
# Create solution record in project
mkdir -p .claude/error-solutions
# Solution file format: [error-type]-[hash].yaml
# .claude/error-solutions/[error-signature].yaml