DonchitosandClaude Opus 5.5
b21fa0f7f2
Fix release for 1.1.1: the minimal path end to end, engine commands that run on Godot, Unity and Unreal, hook warnings you can see, and verdicts that say when they could not check. Details in CHANGELOG.md; upgrade steps in UPGRADING.md (v1.1.1 → v1.1.2). Fixes #67 Fixes #131 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WuJn2FdynEybfL5KC697nJ
3.5 KiB
Error Recovery Protocol
Shared procedure for any skill that spawns agents via the Agent tool. Referenced from the
## Error Recovery Protocol section of each orchestration/review skill. Those
skills keep the two load-bearing imperatives (surface immediately, produce a
partial report) inline, and keep their own Common blockers list inline —
those are skill-specific. This file holds the full procedure.
Trigger 0 — verify the artifact before reading the response
Before applying anything below, and before treating a phase as complete: if the return contract named a path, check that the path exists. A named artifact that is not on disk is a FAILED PHASE, no matter how the agent's response reads.
This trigger exists because the three below are not sufficient. They fire on
BLOCKED, on an error, and on "cannot complete" — and an agent can fail in a way
that is none of those. Observed live: a devops-engineer spawned
as half of a parallel phase ran 26 tool calls and ~31,600 tokens, then
returned a single fluent preamble — "I'll verify the build infrastructure…" —
with no path, no summary, no BLOCKED item, and no file written. Nothing in
steps 1–4 matches that shape. An orchestrator reading the transcript sees a
plausible response and advances, and half a parallel phase disappears with no
signal at all.
The work was not lost — resumed with an explicit "you did not honour the return contract" message, the same agent completed in one tool call, because its investigation was still in context. Only the write-and-return step had failed. So the recovery is cheap; the detection is the hard part, and the detection cannot come from reading the response.
A fluent response is not evidence that a phase ran. The artifact is — observe the artifact, not the transcript. The rule applies to sub-agents exactly as it does to skills.
When the path is missing:
- Do not advance the pipeline or summarise the phase as done.
- Resume the agent, naming the unmet contract explicitly and telling it that "I could not write" is a valid answer but silence is not. Prefer resuming over re-spawning — the context is usually still there, and a re-spawn pays for the whole investigation again.
- If the second attempt also produces nothing, treat it as BLOCKED and apply steps 1–5 below.
If any spawned agent returns BLOCKED, errors, or cannot complete:
- Surface immediately — report "[AgentName]: BLOCKED — [reason]" to the user before continuing to dependent phases. The reason names what is missing and where it was expected (the path or the input), so the user can supply it.
- Assess dependencies — check whether the blocked agent's output is required by subsequent phases. If yes, do not proceed past that dependency point without user input.
- Offer options via
AskUserQuestion:- Skip this agent and note the gap in the final report — never fill the skipped agent's section with content of your own
- Retry with narrower scope
- Stop here and resolve the blocker first
- Always produce a partial report — output whatever was completed. Never discard work because one agent blocked.
- A skip does not clear the block. In a
/team-*pipeline, choosing "skip this agent and note the gap" lets the remaining phases run, but the skipped agent's work is missing from what the pipeline delivers: the final verdict is BLOCKED, naming the skipped agent and its gap — never COMPLETE.