Error Recovery

Error Recovery Patterns

Standard recovery patterns for all squad agents. When something fails, adapt — don't just report the failure.

1. Retry with Backoff

When: Transient failures — API timeouts, rate limits, network errors, temporary service unavailability.

Pattern:

• Wait briefly, then retry (start at 2s, double each attempt)
• Maximum 3 retries before escalating
• Log each attempt with the error received

Example: API call returns 429 Too Many Requests → wait 2s → retry → wait 4s → retry → wait 8s → retry → escalate if still failing.

2. Fallback Alternatives

When: Primary tool or approach fails and an alternative exists.

Pattern:

• Attempt primary approach
• On failure, identify alternative tool/method
• Try the alternative with the same intent
• Document which alternative was used and why

Example: Primary CLI tool fails → fall back to direct API call for the same operation.

3. Diagnose-and-Fix

When: Build failures, test failures, linting errors — structured errors with actionable output.

Pattern:

• Read the full error output carefully
• Identify the root cause from error messages
• Attempt a targeted fix
• Re-run to verify the fix
• Maximum 3 fix-retry cycles before escalating

Example: Build fails with a type error → check for missing import → add it → rebuild.

4. Escalate with Context

When: Recovery attempts have been exhausted, or the failure requires human judgment.

Pattern:

• Summarize what was attempted and what failed
• Include the exact error messages
• State what you believe the root cause is
• Suggest next steps or who might be able to help
• Hand off to the coordinator or the appropriate specialist

Example: After 3 failed build attempts → "Build fails on line 42 with null reference. Tried X, Y, Z. Likely a design issue in the Foo module. Recommend the code owner review."

5. Graceful Degradation

When: A non-critical step fails but the overall task can still deliver value.

Pattern:

• Determine if the failed step is critical to the task outcome
• If non-critical, log the failure and continue
• Deliver partial results with a clear note of what was skipped
• Offer to retry the skipped step separately

Example: Generating a report with 5 sections — section 3 data source is unavailable → produce the report with 4 sections, note that section 3 was skipped and why.

Applying These Patterns

Each agent should reference these patterns in their charter's ## Error Recovery section, tailored to their domain. The charter should list the agent's most common failure modes and map each to the appropriate pattern above.

Selection guide:

| Failure Type | Primary Pattern | Fallback Pattern |

|---|---|---|

| Network/API transient | Retry with Backoff | Escalate with Context |

| Tool/dependency missing | Fallback Alternatives | Escalate with Context |

| Build/test error | Diagnose-and-Fix | Escalate with Context |

| Auth/permissions | Retry with Backoff | Escalate with Context |

| Non-critical data missing | Graceful Degradation | — |

| Unknown/novel error | Escalate with Context | — |