---
name: loop-workflow
description: Loop-driven development discipline — run agents in cycles of work gated by deterministic checks until a stop condition is met. Use when work needs iteration until a measurable criterion holds, when designing retry or verification loops, when a task is too large for one context window, or when choosing between one-shot orchestration and a loop. Triggers on "loop", "iterate until", "keep going until", "run until it passes", "ralph loop", "long-running", or any moment the agent is about to retry work without a defined stop condition.
---

# Loop Workflow

A loop is an agent repeating cycles of work until a stop condition is met. The discipline: **the loop closes on a check, not on a feeling of doneness.** Without a check that produces pass/fail, "looks done" is the only signal available and the human becomes the verification loop.

## The Four Hand-offs

Every loop is defined by what gets handed off to it:

| Loop | Hand off | Draht surface |
|---|---|---|
| Turn-based | the check | TDD cycle inside one task (red → green → refactor → verify) |
| Goal-based | the stop condition | `/orchestrate-loop` (deterministic check + max iterations) |
| Phase-based | the spec | `/execute-phase` → `/verify-work` → `--gaps-only` cycle |
| Session-based | the process | GSD per-phase cycle (`/discuss-phase → /plan-phase → /execute-phase → /verify-work`), fresh context each step |

Pick the smallest loop that fits: a failing test needs the TDD loop, not a goal loop; a roadmap phase needs the phase cycle, not an ad-hoc goal loop.

## Anatomy of a Sound Loop

1. **Deterministic check** — a command whose exit code proves the goal. The loop is only as good as its check; a near-perfect verifier is the highest-leverage component of any loop.
2. **Explicit stop conditions** — criterion met, max iterations, stall. Every loop needs a bound; an unbounded loop is a bug, not persistence.
3. **Independent evaluation** — the agent doing the work never decides completion. Re-run the check outside the worker; route the final verdict to a fresh-context evaluator. Agents systematically overrate their own work.
4. **Recoverable state** — every iteration commits and appends a progress log, so any iteration can die without losing the loop. Fresh iterations run a startup ritual: read the progress log, run the check, observe before changing anything.
5. **One increment per cycle** — small verified steps beat one-shot attempts. Batching increments hides which change broke the check.

## Known Failure Modes → Counters

| Failure mode | Counter |
|---|---|
| Premature completion claims | Independent re-run of the check; evidence before claims |
| Self-graded verification | Fresh-context evaluator (spec-reviewer / reviewer) |
| One-shotting too much per cycle | One increment, one commit per iteration |
| State lost at context death | Commit every iteration + append-only progress log |
| Weakening tests or the check to pass | Tests and check are immutable inside a loop; violation means revert + hard stop |
| Spinning on the same failure | Stall detection — two identical failure signatures in a row means change the inputs, consult `advisor`, or stop |
| Time blindness (hours burned re-running slow checks) | Keep checks fast and their output terse: failures only |

## Interaction With Other Disciplines

- `verification-gate` supplies the evidence rules for reading loop results: label them observed / derived / assumed
- `tdd-workflow` is the innermost loop; `/orchestrate-loop` wraps the same shape at goal level
- `atomic-reasoning` cuts the increments: an increment is well-cut only if its check can fail while all others pass
- `model-tiering` sets the economics: loops are volume work, so workers run on the executor tier while steering (the orchestrating context, `advisor`, `spec-reviewer`) stays on the strongest tier — most loop tokens bill at the worker rate

## Scope

This skill is the discipline reference behind `/orchestrate-loop` and the retry mechanics in `/execute-phase` and `/verify-work`. Consult it before constructing any ad-hoc retry-until-done behaviour.