ALWAYS load before starting any task. Defines systematic recovery procedures when things go wrong during execution. Covers tool failures, build errors, test failures, type errors, and unexpected runtime results. Includes tiered escalation (retry, fallback, memory-informed diagnosis, orchestrator escalation) and post-recovery logging to prevent recurrence.
Defines systematic recovery procedures for tool failures, build errors, and runtime issues with tiered escalation strategies.
/plugin marketplace add mgd34msu/goodvibes-plugin/plugin install goodvibes@goodvibes-marketThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/common-errors.mdscripts/validate-error-recovery.shscripts/
validate-error-recovery.sh
references/
common-errors.md
When tasks fail, agents must follow a systematic recovery process that balances efficiency with thoroughness. This skill defines how to categorize errors, leverage institutional memory, apply multi-source recovery strategies, and know when to escalate.
When an error occurs during task execution:
DO NOT retry blindly. Read the full error message, stack trace, and any diagnostic output.
Categorize the error into one of six types:
Check .goodvibes/memory/failures.json for matching keywords using precision_read:
resolutionCommon Causes:
Recovery Steps:
sandbox.enabled)Common Patterns from Memory:
output.format, handlers read output.mode. Always check both with ??.src/**/*.ts fail silently with ripgrep. Use regex to detect literal prefixes and force fast-glob.path.isAbsolute() before path.resolve().sandbox === true || sandbox === 'true'. Never use === false checks.Common Causes:
Recovery Steps:
npm installCommon Causes:
Recovery Steps:
await, improper use of done(), or race conditionsCommon Causes:
obj.prop where obj could be null/undefined)string assigned to number)any usage escaping type systemRecovery Steps:
explain_type_error analysis-engine tool if available?.) or null checkany escapes: Replace any with proper typesCommon Patterns:
if (obj && 'prop' in obj)obj?.prop?.nestedPropCommon Causes:
Recovery Steps:
.catch() handlers or try/catch around await.env files, verify they're loadedCommon Patterns:
try/catch around all await expressionsif (!value) throw new Error('...')Common Causes:
Recovery Steps:
.goodvibes/secrets/, verify token hasn't expiredCommon Patterns:
After categorizing the error and checking failures.json, use a one-shot strategy where you consult ALL knowledge sources simultaneously (not sequentially) and apply the best solution:
Once you've consulted all sources:
Evaluate solutions based on:
Apply the solution completely:
Validate the fix:
Once you've successfully resolved the error:
.goodvibes/memory/failures.jsonUse precision_edit to append a new entry with:
{
"id": "fail_YYYYMMDD_HHMMSS",
"date": "ISO-8601 timestamp",
"error": "Brief description of the error",
"context": "What was being attempted when error occurred",
"root_cause": "Why it happened (technical explanation)",
"resolution": "How it was fixed (specific steps taken)",
"prevention": "How to avoid this in the future",
"keywords": ["relevant", "search", "terms"]
}
Example:
{
"id": "fail_20260215_143000",
"date": "2026-02-15T14:30:00Z",
"error": "precision_read returns 'file not found' for valid path",
"context": "Reading component file at src/components/Button.tsx",
"root_cause": "Path was relative, but precision tools require absolute paths. Sandbox was enabled, blocking CWD resolution.",
"resolution": "RESOLVED - Used absolute path with process.cwd() to create absolute path before calling precision_read.",
"prevention": "Always use absolute paths with precision tools. Use path.resolve() to convert relative to absolute.",
"keywords": ["precision_read", "path", "absolute", "relative", "sandbox", "file-not-found"]
}
.goodvibes/logs/errors.mdAppend a markdown entry using precision_edit:
## [YYYY-MM-DD HH:MM] ERROR_CATEGORY: Brief Description
**Error**: Full error message
**Context**: What was being done
**Resolution**: How it was fixed
**Time to resolve**: X minutes
---
Once logged, return to the original task. Don't wait for confirmation.
If you've tried to fix the error 3 times and it's still failing:
Add to failures.json with "resolution": "UNRESOLVED - <what was tried>":
{
"id": "fail_20260215_143500",
"date": "2026-02-15T14:35:00Z",
"error": "Vitest tests hang indefinitely on CI",
"context": "Running npm run test in CI pipeline",
"root_cause": "Unknown - tests pass locally but hang in CI environment",
"resolution": "UNRESOLVED - Tried: 1) Added --no-watch flag, 2) Increased timeout to 60s, 3) Disabled coverage collection. Tests still hang.",
"prevention": "Need deeper investigation into CI environment differences",
"keywords": ["vitest", "ci", "hang", "timeout", "unresolved"]
}
Use structured format in your response:
## Task Status: BLOCKED
### Error
[ERROR_CATEGORY] Brief description
### Attempts Made
1. **Attempt 1**: What was tried -> Result
2. **Attempt 2**: What was tried -> Result
3. **Attempt 3**: What was tried -> Result
### Root Cause Analysis
Best guess at why this is failing based on investigation.
### Suggested Next Steps
- Option 1: [Describe approach that requires different permissions/access]
- Option 2: [Describe alternative architecture/design decision]
- Option 3: [Describe manual intervention needed]
### Files Changed
- `path/to/file.ts` - [what was changed during troubleshooting]
Leave the task in BLOCKED state. The orchestrator will decide whether to:
For certain error types, do NOT attempt recovery. Escalate immediately to the orchestrator:
EACCES: permission denied
EPERM: operation not permitted
Why: These require user intervention to grant permissions. Agents can't fix this.
Escalate with: "Permission error encountered. Need user to: [grant file access / run as sudo / change ownership]."
Error: OPENAI_API_KEY is not defined
Error: Database connection failed: authentication error
401 Unauthorized
Why: Agents can't create or modify secrets. Only users can provide credentials.
Escalate with: "Missing credential: [ENV_VAR_NAME or service name]. User needs to provide via .env or secrets management."
Context clues indicate multiple valid approaches:
- Use REST API vs GraphQL
- Use Prisma vs Drizzle
- Component composition pattern unclear
Why: These are design decisions that affect the broader system. Agents shouldn't make architectural choices unilaterally.
Escalate with: "Architectural decision required: [describe the choice]. Options: [list 2-3 options with tradeoffs]."
Original task: "Add user profile page"
Discovered: Requires new database schema, auth changes, API endpoints
Why: The task is larger than originally scoped. Orchestrator needs to re-plan.
Escalate with: "Scope expansion discovered. Original: [task]. Required: [new dependencies/changes]. Recommend: [break into subtasks / get user approval]."
When errors occur:
After 3 attempts:
Escalate immediately for:
Remember:
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.