9. Iterate
Assume chapter 8's evaluation left a failing criterion. Evolve is the feature that applies those evaluation findings to the Seed and runs again.
9.1 What it does
Evaluation ending does not always mean the work is done. Evolve uses the problems found in evaluation to propose changes to the Seed's goal, constraints, and completion criteria, then repeats execution with the changed Seed. In the example, the failure "the done state resets after a refresh" is applied to the next Seed.
9.2 Run
Run this inside the Claude Code session, with a description of the work.
ooo evolve "to-do app: keep the done state after a refresh"Expected result: a Seed change proposal reflecting the evaluation, the run result, and a lineage_id. One generation proceeds as Wonder (find what is still unknown), Reflect (draft the changes), execute, evaluate.
To see only the Seed changes without rebuilding code, add --no-execute. List the runs that followed with ooo evolve --status <lineage_id>.
9.3 lineage — the revision history
One evolve's new Seed and run is called a generation, and the chain of generations from the same starting Seed is called a lineage. Query lineage state with the printed lineage_id.
9.4 Automatic stop conditions
Per the official docs, iteration stops at the first of these conditions.
| Condition | Criterion |
|---|---|
| Convergence | When the Ontology similarity of two consecutive generations is 0.95 or higher, the data structure is considered stable and iteration stops. |
| Stagnation | When similarity stays at or above the Convergence threshold (0.95) for 3 consecutive generations, nothing more is expected to change and iteration stops. |
| Oscillation | Stops when the structure keeps returning to the one from two generations earlier. |
| Generation cap | Stops at a maximum of 30 generations. |
Convergence checks apply only after at least 2 generations have completed.
9.5 Ralph — automatic iteration
Instead of calling evolve yourself each generation, hand the iteration to Ralph until a stop condition is reached. Pass the lineage_id from 9.2.
ooo ralph --lineage-id <lineage_id>Expected result: a background job starts and its job ID is printed. Generations repeat until one of: QA passes, an automatic stop condition from 9.4 (Convergence, Stagnation, Oscillation, or the generation cap), cancellation, an unrecoverable failure, a regressing grade, or a time limit.
9.6 When you should stop it
More automatic iterations do not guarantee quality. Stop the loop and reset direction yourself when:
- The completion criteria are already met.
- The same question or failure repeats.
- The changes are small relative to the cost of running.
- The product direction itself needs a human decision.
Stopping an active run works the same as cancelling in chapter 7.