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:

Condition	Example	Description
`attempt: N`	`attempt: 4`	Applies from attempt N onward (sticky)
`not: <gate>`	`not: gate.test`	Applies if the named gate failed
`validate: <workflow>`	`validate: validators/assess`	Invokes a validator; applies if output = true
`exit: N`	`exit: 6`	Stop 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

Attempt	Agent
1–2	claude-sonnet (from the step)
3–4	claude-sonnet-thinking (sticky)
5–7	claude-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

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

Safety validations

Rule	Behavior
New agent without `session: new`	Gump forces `session: new` + warning
`worktree: reset` with same session	Warning
No `exit:` declared	Error at dry-run

Overview

Getting Started

Writing Workflows

Orchestration

Execution & Data

Agents

Reference

Failure Handling

Failure Handling

Without retry

Basic retry

Overrides

Condition types

Overridable keywords

Sticky behavior

Validator conditions

What happens on retry

Safety validations

​Failure Handling

​Without retry

​Basic retry

​Overrides

​Condition types

​Overridable keywords

​Sticky behavior

​Validator conditions

​What happens on retry

​Safety validations

Failure Handling

Without retry

Basic retry

Overrides

Condition types

Overridable keywords

Sticky behavior

Validator conditions

What happens on retry

Safety validations