Skip to content
rev0by cpc.studioDocs

Run a Goal until it is done

A Goal is a Loop that keeps running until its objective is met. Each iteration is a fresh agent run that takes one step, writes what it found into a ledger, and says whether to go on. Use it for work with no fixed number of steps: a migration, clearing a backlog of warnings, raising coverage until it reaches a number.

Before you begin

Section titled “Before you begin”
  • An objective someone could check. “Improve the tests” never ends; “every module in api/ has a test file and the suite passes” does.
  • A budget you are happy to spend. The caps below are the only thing that stops a Goal that never reports it is done.

Write the objective

Section titled “Write the objective”
  1. Click Create and set Type to Goal (loops until an objective is met).
  2. Under Objective, write what should be true when it is finished.
  3. In the second field, write the done when sentence: the acceptance test, in your words. A model reads the ledger against it, so a concrete test (“a spot check of three modules matches the code”) steers it better than an adjective.
  4. Fill in the rest as for any ticket: a title, a working directory, and anything the agent should know in the description.

Result: the objective and the done when sentence head the Goal’s Goal section, and every iteration gets both in its instructions.

Set the caps

Section titled “Set the caps”

On the same form, before you click Create:

  1. Max iterations: how many runs the Goal may fire (10 by default).
  2. Max cost ($): how much it may spend in total (5 by default).

Each iteration also stops after 30 minutes. The Goal stops at the first cap it reaches.

Result: the Goal section shows a meter for each cap, Iterations and Cost, which turns amber at 80% and red at 100%.

Start it

Section titled “Start it”

A Goal has no schedule: it starts when you ask.

  1. Open the Goal and its Schedule tab.
  2. Click Run now.

Result: the first iteration runs. When it reports continue, the next one fires straight away, until the Goal stops.

Read the ledger

Section titled “Read the ledger”

Each iteration adds one row to the Goal section: its number, its verdict, what it found, and what the next iteration should do (next:). The next iteration is handed the latest rows before it starts, so it picks up where the last one got to instead of rediscovering it. Each iteration is also a run in the Loop’s history, with its own timeline and diff.

VerdictWhat happens
continueThe next iteration fires straight away, if no cap is reached.
doneThe Goal stops: Objective met at iteration N.
blockedThe Goal stops and notifies you: the iteration cannot get further on its own. Read its findings for why.

A Goal also stops, and notifies you, when a cap is reached (Stopped with the objective unmet), when an iteration ends without a verdict, or when you pause it (uncheck Enabled).

Result: the ledger tells you how far the Goal got and why it stopped.

Continue a stopped Goal

Section titled “Continue a stopped Goal”

The ledger is kept, so a Goal carries on from where it stopped:

  1. Fix what stopped it: answer what a blocked iteration needed (in the Goal’s description or a comment), or raise the cap it reached.
  2. Click Run now.

Result: the next iteration starts with the whole ledger. Run now ignores the caps for that one run, but if a cap is still exceeded the Goal stops again after it.

If something goes wrong

Section titled “If something goes wrong”

the iteration ended without reporting goal progress

Section titled “the iteration ended without reporting goal progress”

The run finished without a verdict, so the Goal stopped. It usually means the iteration ran out of time: ask for smaller steps in the description, then Run now.

resource cap reached

Section titled “resource cap reached”

The Goal spent its iterations or its budget before the objective was met. Read the last rows: if it is close, raise the cap and Run now; if it is going in circles, rewrite the done when sentence.

Section titled “Related”