Error Recovery

Detect, automatically recover from, report, and log errors to prevent silent data loss and ensure proper human intervention when needed.

Security Scan

The skill is an internally consistent, instruction-only 4R error-recovery framework with a small local CLI helper; it does not request credentials, installs, or network endpoints and its behavior matches its description.

Purpose & Capability

Name/description (error detection, automatic recovery, reporting, logging) align with the included SKILL.md and the single helper script. The code and docs implement a local diagnostic helper and guidance for retries and reporting—no unrelated capabilities (cloud access, secrets, or unusual binaries) are requested.

Instruction Scope

SKILL.md stays focused on error recognition, retry policies, reporting, and recording lessons. It does recommend writing error logs to memory/errors/YYYY-MM-DD.md and suggests actions such as asking for elevated permissions or installing missing deps; these are reasonable for an error-recovery framework but imply the agent may write files and ask humans for privileged actions. The instructions do not ask the agent to read unrelated system files or exfiltrate data.

Install Mechanism

No install spec is present (instruction-only) and the only code file is a small local CLI script. Nothing is downloaded from external URLs or installed automatically.

Credentials

The skill declares no required environment variables, credentials, or config paths. The SKILL.md mentions checking tokens/permissions in troubleshooting text, but does not require or attempt to access secrets itself.

Persistence & Privilege

always:false and no special privileges requested. The framework recommends recording errors to a local memory/errors path (i.e., saving logs), which is a modest persistence action; this is proportionate but you should confirm where the agent will write logs and with what filesystem permissions.

Assessment

This skill appears coherent and low-risk: it only provides guidance and a small local CLI for diagnosing common errors and does not ask for credentials or install code. Before installing, confirm where the agent will store error logs (memory/errors path) and that you are comfortable it can write to that location. Also: (1) review the scripts locally (the included scripts are readable and contain no network calls), (2) ensure automatic retries are not used for destructive operations in your workflows, and (3) avoid supplying secrets or elevated credentials to the agent unless necessary for a specific human-approved remediation. If you want higher assurance, run the CLI in a sandbox or staging agent first and inspect any files it creates.

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:

1. Stop and acknowledge the error
2. Read the full error message
3. 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