@cryptotaxi247 / SquadScope
Code Commits Issues Pulls Sessions CI/CD
main
main
md 99 lines 3.38 KB
Rendered Raw
1 ---
2 name: "error-recovery"
3 description: "Standard recovery patterns for all squad agents. When something fails, adapt — don't just report the failure."
4 domain: "reliability, agent-coordination"
5 confidence: "high"
6 license: MIT
7 ---
8
9 # Error Recovery Patterns
10
11 Standard recovery patterns for all squad agents. When something fails, **adapt** — don't just report the failure.
12
13 ---
14
15 ## 1. Retry with Backoff
16
17 **When:** Transient failures — API timeouts, rate limits, network errors, temporary service unavailability.
18
19 **Pattern:**
20 1. Wait briefly, then retry (start at 2s, double each attempt)
21 2. Maximum 3 retries before escalating
22 3. Log each attempt with the error received
23
24 **Example:** API call returns 429 Too Many Requests → wait 2s → retry → wait 4s → retry → wait 8s → retry → escalate if still failing.
25
26 ---
27
28 ## 2. Fallback Alternatives
29
30 **When:** Primary tool or approach fails and an alternative exists.
31
32 **Pattern:**
33 1. Attempt primary approach
34 2. On failure, identify alternative tool/method
35 3. Try the alternative with the same intent
36 4. Document which alternative was used and why
37
38 **Example:** Primary CLI tool fails → fall back to direct API call for the same operation.
39
40 ---
41
42 ## 3. Diagnose-and-Fix
43
44 **When:** Build failures, test failures, linting errors — structured errors with actionable output.
45
46 **Pattern:**
47 1. Read the full error output carefully
48 2. Identify the root cause from error messages
49 3. Attempt a targeted fix
50 4. Re-run to verify the fix
51 5. Maximum 3 fix-retry cycles before escalating
52
53 **Example:** Build fails with a type error → check for missing import → add it → rebuild.
54
55 ---
56
57 ## 4. Escalate with Context
58
59 **When:** Recovery attempts have been exhausted, or the failure requires human judgment.
60
61 **Pattern:**
62 1. Summarize what was attempted and what failed
63 2. Include the exact error messages
64 3. State what you believe the root cause is
65 4. Suggest next steps or who might be able to help
66 5. Hand off to the coordinator or the appropriate specialist
67
68 **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."
69
70 ---
71
72 ## 5. Graceful Degradation
73
74 **When:** A non-critical step fails but the overall task can still deliver value.
75
76 **Pattern:**
77 1. Determine if the failed step is critical to the task outcome
78 2. If non-critical, log the failure and continue
79 3. Deliver partial results with a clear note of what was skipped
80 4. Offer to retry the skipped step separately
81
82 **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.
83
84 ---
85
86 ## Applying These Patterns
87
88 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.
89
90 **Selection guide:**
91
92 | Failure Type | Primary Pattern | Fallback Pattern |
93 |---|---|---|
94 | Network/API transient | Retry with Backoff | Escalate with Context |
95 | Tool/dependency missing | Fallback Alternatives | Escalate with Context |
96 | Build/test error | Diagnose-and-Fix | Escalate with Context |
97 | Auth/permissions | Retry with Backoff | Escalate with Context |
98 | Non-critical data missing | Graceful Degradation | — |
99 | Unknown/novel error | Escalate with Context | — |