sharkitect-solutions/error-resolver

Error Resolver

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

5-Step Resolution Process

1. CLASSIFY -- 2. PARSE -- 3. MATCH -- 4. ANALYZE -- 5. RESOLVE

Execute all five steps in sequence. Do not skip steps based on apparent familiarity with the error.

File Index

| File | Purpose | Load When | |------|---------|-----------| | patterns/nodejs.md | Node.js and npm error patterns | Error involves Node.js, npm, or JavaScript runtime | | patterns/python.md | Python error patterns | Error involves Python, pip, or virtualenv | | patterns/react.md | React and Next.js error patterns | Error involves React, JSX, or Next.js | | patterns/database.md | Database error patterns | Error involves SQL, ORM, or DB connections | | patterns/docker.md | Docker and container error patterns | Error involves Docker, containers, or images | | patterns/git.md | Git error patterns | Error involves git commands or repository state | | patterns/network.md | Network and API error patterns | Error involves HTTP, ECONNREFUSED, or API calls | | patterns/go.md | Go error patterns | Error involves Go compilation or runtime | | patterns/rust.md | Rust error patterns | Error involves Rust compilation or cargo | | analysis/stack-trace.md | Stack trace parsing methodology | Stack trace is present and needs systematic parsing | | analysis/root-cause.md | Root cause analysis techniques | 5 Whys analysis is needed for complex failures | | replay/solution-template.yaml | Template for recording solutions | A new solution has been confirmed and should be recorded | | replay/README.md | Replay system overview | Looking up or recording solution patterns |

Error Classification Framework

Primary Categories

| 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, elevated privileges needed | | Dependency | ModuleNotFound, Cannot find module | Missing package, version mismatch | | Configuration | Config error, env missing | Wrong settings, missing environment variables | | Database | Connection refused, query error | DB down, wrong credentials, malformed query | | Memory | OOM, heap out of memory | Memory leak, oversized data processing |

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 or code (e.g., ENOENT, TypeError, ModuleNotFound)
• Error message keywords
• Where it occurred (compile, runtime, test)

Step 2: Parse

Extract all key information before proceeding:

• Error code: [specific code if present]
• 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]

Load analysis/stack-trace.md if a stack trace is present.

Step 3: Match Patterns

Check the relevant patterns/ file for the detected language or error category. Check replay/ for previously recorded solutions matching this error signature. If a match is found, apply the recorded solution and verify before closing.

Step 4: Root Cause Analysis

Apply the 5 Whys technique (load analysis/root-cause.md for complex cases):

• Error: Cannot read property 'name' of undefined
• Why 1 -- user object is undefined
• Why 2 -- API call returned null
• Why 3 -- User ID does not exist in the database
• Why 4 -- ID was from a stale cache
• Why 5 -- Cache invalidation not implemented
• Root Cause: Missing cache invalidation logic

Do not stop at the first plausible cause. Continue until the systemic origin is identified.

Step 5: Resolve

Produce all three resolution layers:

1. Immediate fix -- get it working now
2. Proper fix -- the correct long-term solution
3. Prevention -- how to avoid recurrence

Output Format

Produce this structure for every error resolution:

---

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]

Record confirmed solutions using replay/solution-template.yaml in .claude/error-solutions/.

Debugging Patterns

| Pattern | When to Use | Method | |---------|-------------|--------| | Binary Search | Error location is unclear | Comment out half the code; if error persists it is in the remaining half; repeat | | Minimal Reproduction | Cannot isolate the cause | Build from an empty file, add code until the error appears | | Rubber Duck | Assumptions may be wrong | State what should happen, what actually happens, what changed, and what assumptions exist | | Git Bisect | Regression with unknown origin | Use git bisect to binary-search commits between last-known-good and current |

Rationalization Table

| Rationalization | Why It Is Wrong | |-----------------|-----------------| | I already know what this error means -- I can skip to the fix | Pattern recognition is unreliable without parsing; similar error messages have different root causes across contexts | | This is a simple error, the full workflow is overkill | Simple-looking errors frequently mask systemic issues; skipping analysis produces fixes that recur | | The stack trace tells me everything I need | Stack traces show where an error surfaced, not why it originated; root cause analysis is always required | | The user has already described the cause, I just need to fix it | User diagnosis is a hypothesis, not a root cause; verify before prescribing a solution | | I have seen this exact error before, I know the solution | Prior solutions apply to prior contexts; environment, versions, and code state change the answer | | The fix is obvious from the error message | Error messages are written for humans and are frequently misleading; classification and parsing validate the obvious interpretation | | Checking patterns/ is unnecessary for common errors | The patterns directory contains language-specific edge cases and version-dependent behaviors not held in general knowledge | | I can skip Step 3 because I did not write replay files | Replay files may exist from prior sessions or teammates; always check before treating an error as new |

Red Flags Checklist

Check for these signs that the skill is being violated:

• [ ] Providing a fix without stating the error classification
• [ ] Suggesting code changes before completing the Parse step
• [ ] Stopping at "Why 1" in the 5 Whys analysis
• [ ] Skipping patterns/ lookup because the language seems familiar
• [ ] Omitting the Prevention section from the output
• [ ] Treating the user's stated cause as confirmed without verification
• [ ] Providing only an immediate fix without a proper long-term fix
• [ ] Skipping replay/ lookup before treating the error as novel
• [ ] Producing a solution without a Verification step
• [ ] Closing the resolution before the fix has been confirmed to work

NEVER List

| Prohibition | Why | |-------------|-----| | NEVER skip directly to a code fix without completing Classify and Parse | Fixes applied to misclassified errors introduce new bugs and waste time | | NEVER present a single-layer solution (immediate fix only) | Without the proper fix and prevention layers the error will recur | | NEVER accept the first plausible root cause without applying 5 Whys | Surface causes mask systemic issues; stopping early produces recurring failures | | NEVER omit Verification from the output | An unverified fix is a guess; the resolution is not complete until the fix is confirmed | | NEVER apply a replay solution without verifying it matches the current context | Environments and versions differ; a past solution can be wrong or harmful in a new context | | NEVER diagnose based on the error message alone without reading the stack trace | Error messages are human-readable summaries; stack traces reveal the actual execution path | | NEVER treat missing context as sufficient reason to skip steps | If context is missing, ask for it before proceeding -- do not assume and continue |