Documentation Index
Fetch the complete documentation index at: https://gump.build/docs/llms.txt
Use this file to discover all available pages before exploring further.
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 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
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 -fdprompt — 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
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 |
