1. Encounter Error
       |
       v
2. Check Replay History -----> Match Found? ---> Apply Known Solution
       |                             |
       No Match                      |
       |                             v
       v                        Verify & Done
3. Analyze & Resolve
       |
       v
4. Record Solution ---------> .claude/error-solutions/
       |
       v
5. Future Benefit

Directory Structure

project/
└── .claude/
    └── error-solutions/
        ├── nodejs-module-not-found-express.yaml
        ├── react-hydration-mismatch-date.yaml
        ├── postgres-connection-refused.yaml
        └── ...

Recording Solutions

When to Record

Record a solution when:

You spent significant time debugging
The error is likely to recur
The solution isn't obvious
Team members might encounter same issue

How to Record

Copy the template:

mkdir -p .claude/error-solutions
cp solution-template.yaml .claude/error-solutions/<error-signature>.yaml

Fill in the details:

id: "nodejs-module-not-found-express"
created: "2024-01-15T10:30:00Z"

error:
  type: "dependency"
  category: "ModuleNotFound"
  language: "nodejs"
  pattern: "Cannot find module 'express'"
  context: "Starting Node.js server"

diagnosis:
  root_cause: "Express package not installed"
  factors:
    - "npm install not run after git clone"
    - "package.json missing express"

solution:
  immediate:
    - "Run: npm install express"
  proper:
    - "Add express to package.json if missing"
    - "Run: npm install"

verification:
  - "Run: node server.js"
  - "Check server starts without error"

prevention:
  - "Document npm install in README"
  - "Use npm ci in CI/CD"

metadata:
  tags: ["nodejs", "npm", "dependency"]

Error Signature Generation

Create consistent signatures for matching:

Pattern: `[language]-[category]-[specific]`

Examples:

nodejs-module-not-found-express
react-hydration-mismatch-date
python-import-error-circular
postgres-connection-refused-docker
docker-permission-denied-volume

Normalizing Error Messages

Replace specific values with placeholders:

Original	Normalized
`Cannot find module 'express'`	`Cannot find module '{module}'`
`User 12345 not found`	`User {id} not found`
`Connection refused 127.0.0.1:5432`	`Connection refused {host}:{port}`

Lookup Process

When encountering an error:

1. Generate Signature

Error: Cannot find module 'lodash'
  |
  v
Category: ModuleNotFound
Language: nodejs
  |
  v
Pattern: nodejs-module-not-found-*

2. Search Solutions

# Find matching solutions
ls .claude/error-solutions/ | grep "nodejs-module-not-found"

3. Check Match Quality

# Compare error pattern
error:
  pattern: "Cannot find module '{module}'"  # Matches!

# Check context
context: "Starting Node.js server"  # Same context!

4. Apply Solution

Follow the steps in solution.immediate or solution.proper.

5. Update Metadata

metadata:
  occurrences: 6  # Increment
  last_resolved: "2024-01-20T14:30:00Z"  # Update

Best Practices

Writing Good Solutions

Be Specific

# Bad
root_cause: "Something wrong with dependencies"

# Good
root_cause: "Express package not in node_modules because npm install wasn't run after cloning"

Include Commands

commands:
  - "npm install express"
  - "npm ls express"  # Verify installation

Document Verification

verification:
  - "Server starts without error"
  - "GET /api/health returns 200"

Add Prevention

prevention:
  - "Add postinstall check script"
  - "Document setup in README"

Organizing Solutions

By Language/Framework:

nodejs-*.yaml
python-*.yaml
react-*.yaml

By Error Type:

*-connection-refused-*.yaml
*-module-not-found-*.yaml
*-permission-denied-*.yaml

Version Control

# Add to git
git add .claude/error-solutions/
git commit -m "Add error solution: nodejs-module-not-found-express"

Review Solutions
- Include solutions in code review
- Validate accuracy before merging
Maintain Currency
- Update solutions when better fixes found
- Remove obsolete solutions
- Add timestamps for relevance

Integration with Error Resolver

When using the error-resolver skill:

Automatic Lookup: Check replay history first
Match Scoring: Rate match quality (exact > pattern > category)
Solution Application: Apply known solution if high confidence
Gap Analysis: Identify missing patterns to record
Continuous Learning: Record new solutions after resolution

Example Solutions

Simple: Missing Dependency

id: "nodejs-module-not-found-express"
error:
  type: "dependency"
  pattern: "Cannot find module 'express'"
solution:
  immediate:
    - "npm install express"

Complex: Race Condition

id: "react-state-update-unmounted"
error:
  type: "runtime"
  pattern: "Can't perform a React state update on an unmounted component"
  context: "Async operation completing after component unmount"
diagnosis:
  root_cause: "useEffect cleanup not cancelling async operations"
  factors:
    - "fetch() or setTimeout() completing after unmount"
    - "No cleanup function in useEffect"
solution:
  proper:
    - "Add cleanup function to useEffect"
    - "Use AbortController for fetch"
    - "Track mounted state with ref"
  code_change: |
    useEffect(() => {
      const controller = new AbortController()
      fetch(url, { signal: controller.signal })
        .then(res => res.json())
        .then(setData)
      return () => controller.abort()
    }, [url])

Environment-Specific: Docker

id: "docker-permission-denied-volume"
error:
  type: "permission"
  pattern: "permission denied: '/app/data'"
  context: "Docker container cannot write to mounted volume"
diagnosis:
  root_cause: "Container user doesn't have write permission to host directory"
  factors:
    - "Container runs as non-root user"
    - "Host directory owned by different user"
solution:
  immediate:
    - "chmod 777 /host/path"  # Quick but not secure
  proper:
    - "Match container user ID to host user"
    - "Use named volume instead of bind mount"
  commands:
    - "chown -R 1000:1000 /host/path"

README.md

Replay System

How It Works