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.
npxskills add davila7/claude-code-templates--skill "Error Resolver"Loading…
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
id: "nodejs-module-not-found-express"
created: "2024-01-15T10:30:00Z"
updated: "2024-01-20T14:22:00Z"
error:
type: "dependency"
category: "ModuleNotFound"
language: "nodejs"
pattern: "Cannot find module 'express'"
context: "npm project, missing dependency"
diagnosis:
root_cause: "Package not installed or node_modules corrupted"
factors:
- "Missing npm install after git clone"
- "Corrupted node_modules directory"
- "Package not in package.json"
solution:
immediate:
- "Run: npm install express"
proper:
- "Check package.json has express listed"
- "Run: rm -rf node_modules && npm install"
code_change: null
verification:
- "Run the application again"
- "Check express is in node_modules"
prevention:
- "Add npm install to project setup docs"
- "Use npm ci in CI/CD pipelines"
metadata:
occurrences: 5
last_resolved: "2024-01-20T14:22:00Z"
success_rate: 1.0
tags: ["nodejs", "npm", "dependency"]
When encountering an error:
.claude/error-solutions/ for matching patternssignature = hash(
error_type +
error_code +
normalized_message + # remove specific values
language +
framework
)
Example transformations:
Cannot find module 'express' -> Cannot find module '{module}'TypeError: Cannot read property 'name' of undefined -> TypeError: Cannot read property '{prop}' of undefinedUseful commands during debugging:
# Verbose error output
NODE_DEBUG=* node app.js
# Memory debugging
node --inspect app.js
# Check installed packages
npm ls [package-name]
# Verify package.json
npm ls --depth=0
# Debug mode
python -m pdb script.py
# Check installed packages
pip show [package-name]
pip list
# Check file permissions
ls -la [file]
# Check port usage
lsof -i :[port]
netstat -an | grep [port]
# Check environment variables
env | grep [VAR_NAME]
printenv [VAR_NAME]
# Check disk space
df -h
# Check memory
free -m # Linux
vm_stat # macOS
When the error location is unclear:
Create the smallest code that reproduces the error:
Explain the problem out loud (or to Claude):
Find which commit introduced the bug:
git bisect start
git bisect bad # current commit is bad
git bisect good [last-known-good-commit]
# Git will checkout commits for you to test
git bisect good/bad # mark each as good or bad
git bisect reset # when done
patterns/ - Language-specific error patterns
nodejs.md - Node.js common errorspython.md - Python common errorsreact.md - React/Next.js errorsdatabase.md - Database errorsdocker.md - Docker/container errorsgit.md - Git errorsnetwork.md - Network/API errorsanalysis/ - Analysis methodologies
stack-trace.md - Stack trace parsing guideroot-cause.mdreplay/ - Replay system
solution-template.yaml - Template for recording solutions
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).