davila7--claude-code-templates
wehub-resource-sync
1 行
8.3 KiB
JSON
1 行
8.3 KiB
JSON
{"content": "---\nname: Error Resolver\ndescription: 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.\n---\n\n# Error Resolver\n\nA first-principle approach to diagnosing and resolving errors across all languages and frameworks.\n\n## Core Philosophy\n\n**The 5-step Error Resolution Process:**\n\n```\n1. CLASSIFY -> 2. PARSE -> 3. MATCH -> 4. ANALYZE -> 5. RESOLVE\n | | | | |\n What type? Extract key Known Root cause Fix +\n information pattern? analysis Prevent\n```\n\n## Quick Start\n\nWhen you encounter an error:\n\n1. **Paste the full error** (including stack trace if available)\n2. **Provide context** (what were you trying to do?)\n3. **Share relevant code** (the file/function involved)\n\n## Error Classification Framework\n\n### Primary Categories\n\n| Category | Indicators | Common Causes |\n|----------|------------|---------------|\n| **Syntax** | Parse error, Unexpected token | Typos, missing brackets, invalid syntax |\n| **Type** | TypeError, type mismatch | Wrong data type, null/undefined access |\n| **Reference** | ReferenceError, NameError | Undefined variable, scope issues |\n| **Runtime** | RuntimeError, Exception | Logic errors, invalid operations |\n| **Network** | ECONNREFUSED, timeout, 4xx/5xx | Connection issues, wrong URL, server down |\n| **Permission** | EACCES, PermissionError | File/directory access, sudo needed |\n| **Dependency** | ModuleNotFound, Cannot find module | Missing package, version mismatch |\n| **Configuration** | Config error, env missing | Wrong settings, missing env vars |\n| **Database** | Connection refused, query error | DB down, wrong credentials, bad query |\n| **Memory** | OOM, heap out of memory | Memory leak, large data processing |\n\n### Secondary Attributes\n\n- **Severity**: Fatal / Error / Warning / Info\n- **Scope**: Build-time / Runtime / Test-time\n- **Origin**: User code / Framework / Third-party / System\n\n## Analysis Workflow\n\n### Step 1: Classify\n\nIdentify the error category by examining:\n- Error name/code (e.g., `ENOENT`, `TypeError`)\n- Error message keywords\n- Where it occurred (compile, runtime, test)\n\n### Step 2: Parse\n\nExtract key information:\n```\n- Error code: [specific code if any]\n- File path: [where the error originated]\n- Line number: [exact line if available]\n- Function/method: [context of the error]\n- Variable/value: [what was involved]\n- Stack trace depth: [how deep is the call stack]\n```\n\n### Step 3: Match Patterns\n\nCheck against known error patterns:\n- See `patterns/` directory for language-specific patterns\n- Match error signatures to known solutions\n- Check replay history for previous solutions\n\n### Step 4: Root Cause Analysis\n\nApply the **5 Whys** technique:\n```\nError: Cannot read property 'name' of undefined\n Why 1? -> user object is undefined\n Why 2? -> API call returned null\n Why 3? -> User ID doesn't exist in database\n Why 4? -> ID was from stale cache\n Why 5? -> Cache invalidation not implemented\n\nRoot Cause: Missing cache invalidation logic\n```\n\n### Step 5: Resolve\n\nGenerate actionable solution:\n1. **Immediate fix** - Get it working now\n2. **Proper fix** - The right way to solve it\n3. **Prevention** - How to avoid in the future\n\n## Output Format\n\nWhen resolving an error, provide:\n\n```\n## Error Diagnosis\n\n**Classification**: [Category] / [Severity] / [Scope]\n\n**Error Signature**:\n- Code: [error code]\n- Type: [error type]\n- Location: [file:line]\n\n## Root Cause\n\n[Explanation of why this error occurred]\n\n**Contributing Factors**:\n1. [Factor 1]\n2. [Factor 2]\n\n## Solution\n\n### Immediate Fix\n[Quick steps to resolve]\n\n### Code Change\n[Specific code to add/modify]\n\n### Verification\n[How to verify the fix works]\n\n## Prevention\n\n[How to prevent this error in the future]\n\n## Replay Tag\n\n[Unique identifier for this solution - for future reference]\n```\n\n## Replay System\n\nThe replay system records successful solutions for future reference.\n\n### Recording a Solution\n\nAfter resolving an error, record it:\n\n```bash\n# Create solution record in project\nmkdir -p .claude/error-solutions\n\n# Solution file format: [error-type]-[hash].yaml\n```\n\n### Solution Record Format\n\n```yaml\n# .claude/error-solutions/[error-signature].yaml\nid: \"nodejs-module-not-found-express\"\ncreated: \"2024-01-15T10:30:00Z\"\nupdated: \"2024-01-20T14:22:00Z\"\n\nerror:\n type: \"dependency\"\n category: \"ModuleNotFound\"\n language: \"nodejs\"\n pattern: \"Cannot find module 'express'\"\n context: \"npm project, missing dependency\"\n\ndiagnosis:\n root_cause: \"Package not installed or node_modules corrupted\"\n factors:\n - \"Missing npm install after git clone\"\n - \"Corrupted node_modules directory\"\n - \"Package not in package.json\"\n\nsolution:\n immediate:\n - \"Run: npm install express\"\n proper:\n - \"Check package.json has express listed\"\n - \"Run: rm -rf node_modules && npm install\"\n code_change: null\n\nverification:\n - \"Run the application again\"\n - \"Check express is in node_modules\"\n\nprevention:\n - \"Add npm install to project setup docs\"\n - \"Use npm ci in CI/CD pipelines\"\n\nmetadata:\n occurrences: 5\n last_resolved: \"2024-01-20T14:22:00Z\"\n success_rate: 1.0\n tags: [\"nodejs\", \"npm\", \"dependency\"]\n```\n\n### Replay Lookup\n\nWhen encountering an error:\n1. Generate error signature from the error message\n2. Search `.claude/error-solutions/` for matching patterns\n3. If found, apply the recorded solution\n4. If new, proceed with full analysis and record the solution\n\n### Error Signature Generation\n\n```\nsignature = hash(\n error_type +\n error_code +\n normalized_message + # remove specific values\n language +\n framework\n)\n```\n\nExample transformations:\n- `Cannot find module 'express'` -> `Cannot find module '{module}'`\n- `TypeError: Cannot read property 'name' of undefined` -> `TypeError: Cannot read property '{prop}' of undefined`\n\n## Debug Commands\n\nUseful commands during debugging:\n\n### Node.js\n```bash\n# Verbose error output\nNODE_DEBUG=* node app.js\n\n# Memory debugging\nnode --inspect app.js\n\n# Check installed packages\nnpm ls [package-name]\n\n# Verify package.json\nnpm ls --depth=0\n```\n\n### Python\n```bash\n# Debug mode\npython -m pdb script.py\n\n# Check installed packages\npip show [package-name]\npip list\n```\n\n### General\n```bash\n# Check file permissions\nls -la [file]\n\n# Check port usage\nlsof -i :[port]\nnetstat -an | grep [port]\n\n# Check environment variables\nenv | grep [VAR_NAME]\nprintenv [VAR_NAME]\n\n# Check disk space\ndf -h\n\n# Check memory\nfree -m # Linux\nvm_stat # macOS\n```\n\n## Common Debugging Patterns\n\n### Pattern 1: Binary Search\nWhen the error location is unclear:\n1. Comment out half the code\n2. If error persists, it's in the remaining half\n3. Repeat until you find the exact line\n\n### Pattern 2: Minimal Reproduction\nCreate the smallest code that reproduces the error:\n1. Start with empty file\n2. Add code piece by piece\n3. Stop when error appears\n4. That's your minimal repro case\n\n### Pattern 3: Rubber Duck Debugging\nExplain the problem out loud (or to Claude):\n1. What should happen?\n2. What actually happens?\n3. What changed recently?\n4. What assumptions am I making?\n\n### Pattern 4: Git Bisect\nFind which commit introduced the bug:\n```bash\ngit bisect start\ngit bisect bad # current commit is bad\ngit bisect good [last-known-good-commit]\n# Git will checkout commits for you to test\ngit bisect good/bad # mark each as good or bad\ngit bisect reset # when done\n```\n\n## Reference Files\n\n- **patterns/** - Language-specific error patterns\n - `nodejs.md` - Node.js common errors\n - `python.md` - Python common errors\n - `react.md` - React/Next.js errors\n - `database.md` - Database errors\n - `docker.md` - Docker/container errors\n - `git.md` - Git errors\n - `network.md` - Network/API errors\n\n- **analysis/** - Analysis methodologies\n - `stack-trace.md` - Stack trace parsing guide\n - `root-cause.md` - Root cause analysis techniques\n\n- **replay/** - Replay system\n - `solution-template.yaml` - Template for recording solutions\n"} |