From c519474293a5f0d4ccbb4e237788a89fc1b904ae Mon Sep 17 00:00:00 2001 From: Tamir Dresher Date: Wed, 25 Mar 2026 23:25:06 +0200 Subject: [PATCH 1/3] =?UTF-8?q?feat(skills):=20add=20error-recovery=20skil?= =?UTF-8?q?l=20=E2=80=94=20standard=20agent=20failure=20recovery=20pattern?= =?UTF-8?q?s?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 5 recovery patterns for any squad agent: - Retry with Backoff (transient failures, rate limits) - Fallback Alternatives (tool/approach fails) - Diagnose-and-Fix (build/test/lint errors) - Escalate with Context (exhausted recovery) - Graceful Degradation (non-critical step fails) Includes selection guide mapping failure types to patterns. Battle-tested in production multi-agent deployment. Zero breaking changes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .changeset/error-recovery-skill.md | 6 ++ .../templates/skills/error-recovery/SKILL.md | 99 +++++++++++++++++++ .../templates/skills/error-recovery/SKILL.md | 99 +++++++++++++++++++ 3 files changed, 204 insertions(+) create mode 100644 .changeset/error-recovery-skill.md create mode 100644 packages/squad-cli/templates/skills/error-recovery/SKILL.md create mode 100644 packages/squad-sdk/templates/skills/error-recovery/SKILL.md diff --git a/.changeset/error-recovery-skill.md b/.changeset/error-recovery-skill.md new file mode 100644 index 000000000..075f189ec --- /dev/null +++ b/.changeset/error-recovery-skill.md @@ -0,0 +1,6 @@ +--- +"squad-cli": minor +"squad-sdk": minor +--- + +feat: add error-recovery skill for standard agent failure recovery patterns diff --git a/packages/squad-cli/templates/skills/error-recovery/SKILL.md b/packages/squad-cli/templates/skills/error-recovery/SKILL.md new file mode 100644 index 000000000..ebf38825c --- /dev/null +++ b/packages/squad-cli/templates/skills/error-recovery/SKILL.md @@ -0,0 +1,99 @@ +--- +name: "error-recovery" +description: "Standard recovery patterns for all squad agents. When something fails, adapt — don't just report the failure." +domain: "reliability, agent-coordination" +confidence: "high" +license: MIT +--- + +# 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:** +1. Wait briefly, then retry (start at 2s, double each attempt) +2. Maximum 3 retries before escalating +3. 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:** +1. Attempt primary approach +2. On failure, identify alternative tool/method +3. Try the alternative with the same intent +4. 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:** +1. Read the full error output carefully +2. Identify the root cause from error messages +3. Attempt a targeted fix +4. Re-run to verify the fix +5. 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:** +1. Summarize what was attempted and what failed +2. Include the exact error messages +3. State what you believe the root cause is +4. Suggest next steps or who might be able to help +5. 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:** +1. Determine if the failed step is critical to the task outcome +2. If non-critical, log the failure and continue +3. Deliver partial results with a clear note of what was skipped +4. 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 | — | diff --git a/packages/squad-sdk/templates/skills/error-recovery/SKILL.md b/packages/squad-sdk/templates/skills/error-recovery/SKILL.md new file mode 100644 index 000000000..ebf38825c --- /dev/null +++ b/packages/squad-sdk/templates/skills/error-recovery/SKILL.md @@ -0,0 +1,99 @@ +--- +name: "error-recovery" +description: "Standard recovery patterns for all squad agents. When something fails, adapt — don't just report the failure." +domain: "reliability, agent-coordination" +confidence: "high" +license: MIT +--- + +# 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:** +1. Wait briefly, then retry (start at 2s, double each attempt) +2. Maximum 3 retries before escalating +3. 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:** +1. Attempt primary approach +2. On failure, identify alternative tool/method +3. Try the alternative with the same intent +4. 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:** +1. Read the full error output carefully +2. Identify the root cause from error messages +3. Attempt a targeted fix +4. Re-run to verify the fix +5. 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:** +1. Summarize what was attempted and what failed +2. Include the exact error messages +3. State what you believe the root cause is +4. Suggest next steps or who might be able to help +5. 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:** +1. Determine if the failed step is critical to the task outcome +2. If non-critical, log the failure and continue +3. Deliver partial results with a clear note of what was skipped +4. 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 | — | From 868810bcb24f6069c95cd67239ebd38017e13c4c Mon Sep 17 00:00:00 2001 From: tamirdresher Date: Thu, 26 Mar 2026 10:29:04 +0200 Subject: [PATCH 2/3] fix: correct changeset package names to @bradygaster scoped names per FIDO review --- .changeset/error-recovery-skill.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.changeset/error-recovery-skill.md b/.changeset/error-recovery-skill.md index 075f189ec..ec48a85a3 100644 --- a/.changeset/error-recovery-skill.md +++ b/.changeset/error-recovery-skill.md @@ -1,6 +1,5 @@ --- -"squad-cli": minor -"squad-sdk": minor +"@bradygaster/squad-cli": minor +"@bradygaster/squad-sdk": minor --- - -feat: add error-recovery skill for standard agent failure recovery patterns +feat: add error-recovery skill for standard agent failure recovery patterns \ No newline at end of file From bdfaf155a629ade80f273461c4f1254f9a9735d9 Mon Sep 17 00:00:00 2001 From: tamirdresher Date: Thu, 26 Mar 2026 10:40:30 +0200 Subject: [PATCH 3/3] feat: add proposal document for error-recovery skill per review policy --- docs/proposals/error-recovery.md | 69 ++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 docs/proposals/error-recovery.md diff --git a/docs/proposals/error-recovery.md b/docs/proposals/error-recovery.md new file mode 100644 index 000000000..9661c6ea5 --- /dev/null +++ b/docs/proposals/error-recovery.md @@ -0,0 +1,69 @@ +# Proposal: Error Recovery Skill + +**Issue:** bradygaster/squad#623 +**Author:** tamirdresher +**Date:** 2026-03-26 +**Status:** Proposal + +--- + +## Problem Statement + +When a Squad agent fails (model timeout, tool error, invalid output, context overflow), there is +no standardized recovery pattern. Individual coordinators implement ad-hoc retry logic or simply +fail the task. This causes inconsistent user experience and missed opportunities for graceful +degradation across the squad. + +--- + +## Proposed Approach + +A skill library providing five recovery patterns an agent can apply when it encounters a failure: + +| Pattern | When to use | +|---------|-------------| +| **retry** | Transient errors (rate limit, timeout) — wait and retry same approach | +| **fallback** | Primary approach consistently fails — switch to alternative method | +| **diagnose** | Unclear failure cause — gather diagnostics before deciding | +| **escalate** | Blocked beyond agent capability — surface to coordinator/human | +| **degrade** | Full functionality unavailable — deliver partial result with caveat | + +The skill provides a selection guide table mapping error symptoms to the appropriate pattern, +plus prompt templates for each pattern that agents can use in their reasoning. + +--- + +## Fit with Existing Architecture + +- **Complements** existing gent-conduct skill (which covers behavior) — this skill covers failure states +- **No code changes** — template-only, agents apply this via their prompt reasoning +- **Coordinator-agnostic** — works with any existing coordinator style +- **Consistent with** the 3-cycle protocol from iterative-retrieval skill + +--- + +## What Changes + +- New skill: packages/squad-cli/templates/skills/error-recovery/SKILL.md +- New skill: packages/squad-sdk/templates/skills/error-recovery/SKILL.md +- New changeset: .changeset/error-recovery-skill.md + +## What Stays the Same + +- No existing skills modified +- No CLI or SDK runtime code changed + +--- + +## Risks and Mitigations + +| Risk | Likelihood | Impact | Mitigation | +|------|-----------|--------|------------| +| Agents over-apply retry (masking root causes) | Low | Medium | Skill explicitly limits retry to 3 attempts max | +| Conflicts with future built-in error handling | Low | Low | Template-only — superseded naturally if runtime handles it | + +--- + +## References + +- Issue: bradygaster/squad#623