Self-Healing Agent

Auto-detect, classify, retry, and learn from failures.

Error Handling Protocol

1. Detect & Classify

When a tool call fails, classify immediately:

• TRANSIENT — Network timeout, rate limit, temporary unavailability -> retry with backoff
• PERMANENT — Invalid input, missing resource, permission denied -> switch approach
• DEGRADED — Partial result, truncated output -> supplement with alternative

2. Retry Strategy

Attempt 1: Original call
Attempt 2: Wait 5s, retry with same parameters
Attempt 3: Wait 15s, try alternative tool/approach (see table below)
Attempt 4: Log failure, notify user, suggest manual intervention

Never retry endlessly. 3 retries max, then escalate.

3. Alternative Approaches

4. Error Logging

After any non-trivial failure, save a feedback memory if the fix reveals a reusable pattern:

---
name: error-pattern-{descriptive-slug}
description: {tool} fails when {condition} — fix: {solution}
type: feedback
---

{Tool} fails when {specific condition}.

**Why:** {root cause}
**How to apply:** {prevention rule for future sessions}

Only log patterns worth remembering. Don't log one-off transient failures.

5. Pattern Recognition

During self-improvement reviews, check for error patterns:

• Same tool failing repeatedly -> check if service is down or config changed
• Same error type across tools -> likely systemic (network, auth, permissions)
• Recurring at specific times -> schedule-related (maintenance windows, rate resets)

When a pattern is detected, add a prevention rule to relevant skill files.

Auto-Fix Common Issues

Rate Limits (HTTP 429)

• Stop all calls to that service immediately
• Wait 5 minutes minimum
• Resume with reduced frequency

File/Path Errors (Windows/Unix)

• Normalize paths (forward slashes, expand ~)
• Check existence before operations
• Create parent directories automatically for writes
• Remember: Windows paths need /c/Users/... in bash, C:\Users\... in tool calls

Git Conflicts

• Don't force-push or reset without user confirmation
• Stash work before destructive operations
• Check status before any git operation

Permission Denied

• Check if file is read-only or locked
• Check if running as correct user
• Don't retry with sudo without asking

Self-Improvement Loop

1. Every error teaches something -> log patterns worth remembering
2. Every pattern detected -> add prevention rule to relevant skill
3. Every prevention rule -> fewer future errors
4. Review during weekly self-improvement -> prune outdated rules

Integration Points

• deploy-pipeline: Apply retry logic to SCP/SSH operations
• polymarket-vps-ops: SSH timeout recovery follows this protocol
• researcher: WebSearch/WebFetch failures -> alternative approaches
• self-improvement: Error pattern review during weekly cycle