`reflect`

Turn a failure into the next plan. Core syntax

Syntax

when it fails: reflect, then plan again

What it does

The back-edge — the loop's working memory. On a failed check, reflect reads the failure output and writes a short diagnosis, which becomes context for the next plan. The difference between retrying blindly and learning from each miss.

Without a back-edge, a loop that fails its done when check simply tries again from the same starting state and tends to make the same mistake — burning tokens on a thrash. reflect breaks that cycle by inserting a diagnosis step between observe and the next plan: it names why the last cycle failed so the next plan starts from a hypothesis instead of a blank slate. You steer what it looks at with reflect on <focus> — for example reflect on which layer broke tells the agent to localize the failure to a component before re-planning. This is within-run memory; its across-run counterpart is remember in, which persists lessons to a file. Two things make reflect actually work: the failure output has to reach the next plan (end your look at: with and the last failure), and every reflect back-edge needs a floor — an after N tries: stop and warn guard — so a loop that can't diagnose its way out eventually halts instead of looping forever.

Example

when it fails: reflect on which layer broke, then plan again

the reflect back-edge

loop "fix the checkout total":
  goal: cart total is correct with tax and discounts
  look at: src/cart/, src/tax/, and the last failure
  done when "pnpm test cart" passes
  each cycle: plan, then act, then observe
  when it fails: reflect on which layer broke, then plan again
  after 6 tries: stop and warn "thrashing on the total"

reflect wired into a full loop, floored by a thrash guard

How it runs

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

Common mistakes

Forgetting and the last failure in look at:. reflect writes a diagnosis, but the next plan only sees it if the failure is in scope. Without that trailing item the loop reflects into a void and repeats itself — the single most common reason a reflect loop still thrashes.
A back-edge with no floor. when it fails: reflect, then plan again creates an unbounded retry. Always pair it with after N tries: stop and warn so a loop that can't diagnose its way out halts instead of burning tokens forever.
Reflecting on nothing specific. A bare reflect is fine, but reflect on <focus> aims the diagnosis (which layer, which test, which assumption). A vague focus yields a vague plan; name the axis the failure is most likely to live on.

reflect