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

# Debugging

> When a run stalls, fails repeatedly, or produces unexpected results.

# Debugging

When a run stalls, fails repeatedly, or produces unexpected results, Gump gives you several tools to understand what happened.

## The terminal display

During a run, Gump shows progress by turn:

```
[build/task-1/converge] (claude-sonnet) ...
     T1  exploration    3 read             1.2k tok   12s
     T2  coding         2 write, 1 bash    4.8k tok   34s
     ✓ done 54s | $0.12 | 12k/200k ctx (6%) | 3 turns
     ✓ compile | ✓ test | ✗ review
     → retry 2/6 — prompt override
```

Each line shows the turn number, a classified label (coding, execution, exploration, planning, reasoning, reviewing, writing, mixed), action counts, tokens, and duration. Labels are deterministic heuristics — no LLM involved.

## Verbose mode

```bash theme={null}
gump run tdd --spec spec.md --verbose
```

In verbose mode, each turn expands to show individual actions. More than 20 actions per turn shows the first 10 + `... +N more`.

## Error messages

Gump's error messages are contextual. At the end of a failed run:

```
Run failed at step build/task-1/impl (exit after 6 attempts)

  → gump report --detail build/task-1/impl    view step details
  → gump run --replay --from-step impl        retry from a clean state
  → gump run --resume                         continue from current state
```

## Common issues

**The agent runs out of turns** — The `max_turns` guard killed it. Increase the limit or simplify the task.

**The gate keeps failing on test** — Check `gump report --detail` for the test stderr. If the error is in the test infrastructure, the agent can't fix it.

**The cost is higher than expected** — Escalations are the main cost driver. Consider starting with a slightly more capable agent.

**The agent writes files it shouldn't** — The `no_write` guard catches this for split/validate steps. For code steps, use `untouched: "glob"` in the gate.