Error Resolver

A first-principle approach to diagnosing and resolving errors across all languages and frameworks.

Core Philosophy

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

Quick Start

When you encounter an error:

1. Paste the full error (including stack trace if available)
2. Provide context (what were you trying to do?)
3. Share relevant code (the file/function involved)

Error Classification Framework

Primary Categories

Secondary Attributes

• Severity: Fatal / Error / Warning / Info
• Scope: Build-time / Runtime / Test-time
• Origin: User code / Framework / Third-party / System

Analysis Workflow

Step 1: Classify

Identify the error category by examining:

• Error name/code (e.g., ENOENT, TypeError)
• Error message keywords
• Where it occurred (compile, runtime, test)

Step 2: Parse

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]

Step 3: Match Patterns

Check against known error patterns:

• See patterns/ directory for language-specific patterns
• Match error signatures to known solutions
• Check replay history for previous solutions

Step 4: Root Cause Analysis

Apply 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

Step 5: Resolve

Generate actionable solution:

1. Immediate fix - Get it working now
2. Proper fix - The right way to solve it
3. Prevention - How to avoid in the future

Output Format

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]

Replay System

The replay system records successful solutions for future reference.

Recording a Solution

After resolving an error, record it:

1# Create solution record in project
2mkdir -p .claude/error-solutions
3
4# Solution file format: [error-type]-[hash].yaml

Solution Record Format

 1# .claude/error-solutions/[error-signature].yaml
 2id: "nodejs-module-not-found-express"
 3created: "2024-01-15T10:30:00Z"
 4updated: "2024-01-20T14:22:00Z"
 5
 6error:
 7  type: "dependency"
 8  category: "ModuleNotFound"
 9  language: "nodejs"
10  pattern: "Cannot find module 'express'"
11  context: "npm project, missing dependency"
12
13diagnosis:
14  root_cause: "Package not installed or node_modules corrupted"
15  factors:
16    - "Missing npm install after git clone"
17    - "Corrupted node_modules directory"
18    - "Package not in package.json"
19
20solution:
21  immediate:
22    - "Run: npm install express"
23  proper:
24    - "Check package.json has express listed"
25    - "Run: rm -rf node_modules && npm install"
26  code_change: null
27
28verification:
29  - "Run the application again"
30  - "Check express is in node_modules"
31
32prevention:
33  - "Add npm install to project setup docs"
34  - "Use npm ci in CI/CD pipelines"
35
36metadata:
37  occurrences: 5
38  last_resolved: "2024-01-20T14:22:00Z"
39  success_rate: 1.0
40  tags: ["nodejs", "npm", "dependency"]

Replay Lookup

When encountering an error:

1. Generate error signature from the error message
2. Search .claude/error-solutions/ for matching patterns
3. If found, apply the recorded solution
4. If new, proceed with full analysis and record the solution

Error Signature Generation

signature = 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 undefined

Debug Commands

Useful commands during debugging:

Node.js

 1# Verbose error output
 2NODE_DEBUG=* node app.js
 3
 4# Memory debugging
 5node --inspect app.js
 6
 7# Check installed packages
 8npm ls [package-name]
 9
10# Verify package.json
11npm ls --depth=0

Python

1# Debug mode
2python -m pdb script.py
3
4# Check installed packages
5pip show [package-name]
6pip list

General

 1# Check file permissions
 2ls -la [file]
 3
 4# Check port usage
 5lsof -i :[port]
 6netstat -an | grep [port]
 7
 8# Check environment variables
 9env | grep [VAR_NAME]
10printenv [VAR_NAME]
11
12# Check disk space
13df -h
14
15# Check memory
16free -m  # Linux
17vm_stat  # macOS

Common Debugging Patterns

Pattern 1: Binary Search

When the error location is unclear:

1. Comment out half the code
2. If error persists, it’s in the remaining half
3. Repeat until you find the exact line

Pattern 2: Minimal Reproduction

Create the smallest code that reproduces the error:

1. Start with empty file
2. Add code piece by piece
3. Stop when error appears
4. That’s your minimal repro case

Pattern 3: Rubber Duck Debugging

Explain the problem out loud (or to Claude):

1. What should happen?
2. What actually happens?
3. What changed recently?
4. What assumptions am I making?

Pattern 4: Git Bisect

Find which commit introduced the bug:

1git bisect start
2git bisect bad  # current commit is bad
3git bisect good [last-known-good-commit]
4# Git will checkout commits for you to test
5git bisect good/bad  # mark each as good or bad
6git bisect reset  # when done

Reference Files

• patterns/ - Language-specific error patterns

  • nodejs.md - Node.js common errors
  • python.md - Python common errors
  • react.md - React/Next.js errors
  • database.md - Database errors
  • docker.md - Docker/container errors
  • git.md - Git errors
  • network.md - Network/API errors

• analysis/ - Analysis methodologies

  • stack-trace.md - Stack trace parsing guide
  • root-cause.md - Root cause analysis techniques

• replay/ - Replay system

  • solution-template.yaml - Template for recording solutions