> ## 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.

# 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.

```yaml theme={null}
- name: impl
  type: code
  run:
    agent: claude-sonnet
  gate: [compile, test]
  # no retry → gate fail = run stops
```

## Basic retry

```yaml theme={null}
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:

```yaml theme={null}
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.

```yaml theme={null}
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:

```yaml theme={null}
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

| 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                     |