Skip to main content

​
Failure Handling

When a gate fails, the retry block determines what happens next. The retry relaunches the step from GET with the current state — which has changed (error context, gate results are now available).

​
Without retry

If a step has no retry, any gate failure is fatal — the run stops immediately. 
- name: impl
  type: code
  run:
    agent: claude-sonnet
  gate: [compile, test]
  # no retry → gate fail = run stops

​
Basic retry

retry:
  - exit: 3
Retry up to 3 attempts, everything same. The prompt resolves differently because {error}, {diff}, {gate.*} are now in the state.

​
Overrides

Each retry entry declares a condition and optional keyword overrides: 
retry:
  - attempt: 2
    prompt: |
      Deviations remain: {gate.review.comments}
      Fix only these. Files: {task.files}
  - attempt: 4
    agent: claude-opus
    session: new
    worktree: reset
  - exit: 6
Reading: “From attempt 2, use a targeted prompt. From attempt 4, switch to Opus with a fresh session and reset worktree. At attempt 6, stop.”

​
Condition types

Each entry has exactly one condition:
ConditionExampleDescription
attempt: Nattempt: 4Applies from attempt N onward (sticky)
not: <gate>not: gate.testApplies if the named gate failed
validate: <workflow>validate: validators/assessInvokes a validator; applies if output = true
exit: Nexit: 6Stop retrying at attempt N → step FATAL
exit is mandatory — a retry without exit is a dry-run error.

​
Overridable keywords

Retry entries can override these keywords:
  • agent — switch to a different agent (escalation)
  • session — force new (automatic when agent changes)
  • worktree — reset to git reset --hard + git clean -fd
  • prompt — replace the entire prompt (disables automatic retry context injection)

​
Sticky behavior

Overrides are sticky: an override activated at attempt N stays active for N+1, N+2, etc. A later entry overriding the same keyword replaces it. 
retry:
  - attempt: 3
    agent: claude-sonnet-thinking
  - attempt: 5
    agent: claude-opus
  - exit: 7
AttemptAgent
1–2claude-sonnet (from the step)
3–4claude-sonnet-thinking (sticky)
5–7claude-opus (sticky)

​
Validator conditions

A workflow validator can be used as a retry condition — the “agent assess” pattern: 
retry:
  - validate: validators/assess-distance
    with:
      diff: "{diff}"
      error: "{error}"
      agent: claude-haiku
    agent: claude-opus
  - not: gate.test
    agent: claude-opus
  - exit: 6
The validator is invoked at each retry evaluation. Its inputs are passed via with: (separate from the step overrides). If its output is true, the entry’s overrides apply.

​
What happens on retry

  1. The state is updated with error context ({error}, {diff}, {gate.*})
  2. Previous iteration keys are moved to prev namespace
  3. The step relaunches from GET with the updated state
  4. If worktree: reset is active, the worktree is reset to pre-step state
  5. If the prompt is not overridden, the context builder injects a retry section automatically
  6. If the prompt is overridden, no automatic injection — the developer controls everything

​
Safety validations

RuleBehavior
New agent without session: newGump forces session: new + warning
worktree: reset with same sessionWarning
No exit: declaredError at dry-run