| name | error-recovery |
| description | 4R error recovery framework. Recognize, Rescue, Report, Remember. Never lose work silently. Trigger on: 'error', 'failed', 'crash', 'something went wrong', 'retry'. |
Error Recovery 🚨
4R framework. Never lose work silently.
The 4 Rs
R1: RECOGNIZE → Did something go wrong?
R2: RESCUE → Can I recover automatically?
R3: REPORT → Does the human need to know?
R4: REMEMBER → What should I learn from this?
R1: RECOGNIZE (Don't Ignore Errors)
Error signals I must not ignore:
□ Command exit code ≠ 0
□ Exception thrown
□ Timeout exceeded
□ Empty/unexpected output
□ "error", "failed", "exception" in logs
□ Behavior different from expected
Anti-patterns:
- ❌ Command failed, but I continue anyway
- ❌ Error logged, but not mentioned in my response
- ❌ "Probably fine" without verification
What to do:
- Stop and acknowledge the error
- Read the full error message
- Check if it's recoverable or needs human input
R2: RESCUE (Can I Fix It?)
Automatic recovery strategies:
| Error Type | Recovery Strategy |
|---|
| Network timeout | Retry with exponential backoff (max 3) |
| Rate limit | Wait and retry |
| Missing dependency | Install/suggest installation |
| Permission denied | Suggest elevated permissions or fix |
| File not found | Create or point to correct path |
| Invalid input | Sanitize or request correct input |
| API error | Check status, retry if transient |
Retry protocol:
Attempt 1: Immediate
Attempt 2: Wait 5 seconds
Attempt 3: Wait 15 seconds
If all fail → Report to human
When NOT to auto-retry:
- Authentication errors (wrong credentials)
- Permission errors (needs human action)
- Data validation errors (needs correct input)
- Destructive operation failures (don't risk double-execution)
R3: REPORT (Does Human Need to Know?)
Always report when:
- Auto-recovery failed after 3 attempts
- Error affects the final outcome
- Human action is required
- Something unexpected happened
Report format:
⚠️ Error encountered: [brief description]
What happened:
[What I was doing]
Error details:
[Full error message]
What I tried:
[Recovery attempts made]
Current state:
[What's broken / what's still working]
What I need:
[What human action is needed, if any]
Example:
⚠️ Error encountered: GitHub push failed
What happened:
Pushing to aptratcn/cognitive-debt-guard
Error details:
fatal: could not read Username for 'https://github.com'
What I tried:
1. Retried push (failed)
2. Checked git remote config
Current state:
- Commit is saved locally
- Not pushed to remote
What I need:
Git credentials not configured. Will try using token auth.
R4: REMEMBER (Learn From Errors)
After error recovery:
□ Did this error happen before?
→ If yes, what's the pattern?
→ Document the fix
□ Could this happen again?
→ Add guard for this case
→ Update skill/workflow
□ Is there a systemic issue?
→ Suggest process improvement
→ Update AGENTS.md if needed
Error log:
memory/errors/YYYY-MM-DD.md
## [Error Type] - [Timestamp]
**Context:** What I was doing
**Error:** Full error message
**Cause:** Root cause (if known)
**Fix:** How I resolved it
**Prevention:** How to avoid in future
Quick Reference
ERROR → STOP → READ ERROR → CAN I FIX?
↓
NO → REPORT to human → WAIT for action
YES → FIX → VERIFY → CONTINUE
↓
Still broken? → REPORT
Trigger Phrases
- "error", "failed", "crash"
- "something went wrong", "exception"
- "retry", "try again"
- "报错", "失败", "错误"
Integration
- EVR Framework — Verify after recovery
- Systematic Debugging — When root cause is unknown
- Workflow Checkpoint — Save state before risky operations
License
MIT
