`loop`

A self-correcting unit of work. Compose

Syntax

loop "<name>":

What it does

The core construct of LoopFlow: a goal, a way to verify it (done when), the repeated steps (each cycle), and what to do on failure. Every cycle runs plan → act → observe, then the done when predicate decides — pass and the loop stops, fail and it reflects the failure into the next plan. That back-edge is the whole point: a loop is a normal agent that checks its own work and tries again until a verifiable definition of done is met.

Reach for a loop when the task is repeatable and "done" is checkable — a bug with a failing test, a refactor gated by a command, a migration with a verification step. If there's no way to verify completion, there's no loop; the done when line is written first, before any behavior, because a check that can never pass loops forever. The smallest real loop is just a goal and a done when; everything else — look at: for scope, human gates for risky work, after N tries for a thrash guard — is added as the job demands. Blocks start at column 0 and their body is indented two spaces.

Example

loop "fix the failing checkout tax test":
  goal: the tax line is correct at checkout
  done when "pnpm test checkout" passes
  each cycle: plan, then act, then observe
  when it fails: reflect, then plan again

examples/fix_test.loop

How it runs

Every cycle runs plan → act → observe; the done when check decides — pass → stop, fail → reflect into the next plan.

Example — with a thrash guard

loop "fix billing apostrophe bug":
  goal: settings save when the company name has an apostrophe
  done when the test "billing.spec.ts::apostrophe" passes
  look at: billing/form.tsx, api/settings.ts, and the last failure
  when it fails: reflect, then plan again
  after 6 tries: stop and warn "thrashing"

the finish line first, the safety net last

Common mistakes

A loop with no done when. A loop requires a goal, but a goal without a verifiable check is just a prompt — the loop can never confirm it's finished. Write the done when line before any behavior.
A back-edge with no ceiling. Never emit when it fails: reflect without an after N tries: stop and warn. A reflect edge with no floor can loop forever on a check that never goes green.
Paraphrasing the predicate command. The shell command in done when runs verbatim in your shell — quote it exactly. A misremembered command is a loop that can never pass.
Indentation drift. loop sits at column 0; its body is indented two spaces. Mixed indentation is the most common parse error — run loop-run show file.loop to check the shape.

loop