Reference · Canonical Language

Loop Engineering — Glossary

The working vocabulary for this course. Once a term lives here, every lesson uses this word for it — the loop you can name is the loop you can fix. Grows as we go.

The Three Loops

Tool loop · inner loop, within a turn

The loop inside a single agent turn: the model emits a response, the harness runs any tool call, the result is appended, and the model is queried again — stopping at "no pending tool calls." A stuck tool loop shows up in the trace as the same call repeating with similar arguments and no final assistant message.

Avoid: reaching for a plan rewrite when the symptom is a spinning tool loop — the fix is an iteration cap, not a new plan.

Source: three-loops-agentic-coding · Lesson: The Three Loops

Verification loop · tests as boundary

The mid loop that runs the code, observes a failure, feeds the error back, and re-checks. Its boundary is binary and machine-checkable: a test or build runs green. It stops only when the verifier says PASS — "the agent thinks it's done" does not count.

Avoid: accepting a green-looking summary as a pass; the verification tool, not the agent's narration, is the boundary.

Source: three-loops-agentic-coding · Lesson: The Three Loops

Convergence loop · outer loop, stable state as boundary

The outer plan → act → verify loop across turns whose stopping boundary is a stable state, not a test gate. For prose, specs, and partly-specified code no machine-checkable gate exists, so it leans on convergence signals; its failure mode is progress that never converges — oscillating diffs, drifting scope, output that grows each turn.

Source: three-loops-agentic-coding · Lesson: The Three Loops

Context rot · the dumb zone

The non-linear degradation of reasoning quality as the context window fills — practitioners' "dumb zone" past roughly 60–70% fill, where compaction starts discarding load-bearing instructions. It is the liability accumulated-context loops trade against and the reason fresh-context loops exist.

Source: loop-strategy-spectrum · Lesson: Loop Strategy & Autonomy

Strategy and Context

Accumulated context

A loop strategy that keeps one growing session so the agent can cross-reference findings, spot patterns, and avoid repeating failed approaches — the right choice for synthesis and discovery, at the cost of context rot on long runs. Chosen by workload, not habit.

Avoid: accumulated context for execution-heavy, unattended work — the window fills and instruction-following degrades.

Source: loop-strategy-spectrum · Lesson: Loop Strategy & Autonomy

Fresh-context (Ralph) loop · Ralph Wiggum loop

A loop that starts each iteration with a clean context window, reads persistent state from disk, completes one bounded task, and writes results back before restarting. State lives in files, not conversation history — so context rot cannot accumulate and a failed iteration resumes cleanly from the last successful write.

Avoid: a fresh-context loop on tasks whose continuity is load-bearing (extended negotiation, stateful debugging) — the lost context was the work.

Source: ralph-wiggum-loop · Lesson: Loop Strategy & Autonomy

Completion audit

The evidence-mapped check a goal-driven loop demands before the agent may declare "done": restate the objective as concrete deliverables, map every requirement to inspected evidence, and reject proxy signals — intent, partial progress, memory of earlier work, a plausible final answer. The load-bearing element of the goal-driven loop, and the part most often lost across compaction.

Source: goal-driven-autonomous-loop · Lesson: Loop Strategy & Autonomy

Separate-context grader

A grader that scores the loop's output in its own context window, so it is not influenced by the main agent's implementation choices. The structural defense against self-audit confirmation bias — when the worker is also the auditor, long transcripts produce false-positive completion.

Avoid: trusting a same-session self-audit on a long run; splitting the maker from the checker is what closes the bias.

Source: goal-driven-autonomous-loop · Lesson: Loop Strategy & Autonomy

Structure and Middleware

Loop middleware · deterministic nodes

Deterministic nodes that wrap the agent loop from the outside, guaranteeing critical steps and injecting input at loop boundaries regardless of model compliance. Either the agent does the step or the middleware does, and the outcome is the same. It acts at loop boundaries — distinct from per-tool-call hooks inside the loop and CI checks after it.

Source: agent-loop-middleware · Lesson: Loop Structure & Orchestration

Post-loop safety net

A middleware node that runs after the loop exits and performs a skipped critical step deterministically — open the PR, commit, persist state, update the ticket — doing nothing if the agent already did it. It relies on idempotency and verifiable state.

Avoid: firing it off assumed state; if the pr_opened flag can be wrong, the net opens a second PR. Watch its fire-rate — a climbing rate hides an upstream prompt or tooling problem.

Source: agent-loop-middleware · Lesson: Loop Structure & Orchestration

Pre-call message injection

A middleware node that drains a queue of human or external messages — Slack, Linear, GitHub comments — into the conversation before each model call, steering a running loop without restarting it. The substrate that lets a checkpointed loop resume with human input.

Source: agent-loop-middleware · Lesson: Loop Structure & Orchestration

Idempotency

The property that re-running an operation produces the same result, not a doubled one. It is the precondition a post-loop safety net needs: re-doing a step the agent already did must be harmless, which means safety nets are built around verifiable state, never assumed state.

Source: agent-loop-middleware · Lesson: Loop Structure & Orchestration

HITL checkpoint · human-in-the-loop, inside the loop

A human checkpoint inside the loop is a control primitive, not a safety wrapper: the loop suspends, persists state, and waits for a decision that determines what the next iteration does. It earns its cost only at sparse placements — low confidence, budget threshold, irreversible action.

Avoid: per-iteration checkpoints — they saturate the human at machine speed and become rubber-stamping under load. Pair every interrupt with a timeout default.

Source: human-in-the-loop-checkpoints · Lesson: Loop Structure & Orchestration

Decision verbs · approve / edit / reject / respond

The four loop-control replies a checkpoint exposes: approve (continue unchanged), edit (replace the action's arguments, then continue), reject (skip the action; the model gets the rejection as tool feedback and re-plans), respond (synthesize a tool result from the human's reply). Reject and respond change what the loop iterates on next — the checkpoint is part of the loop's transition function, not external to it.

Source: human-in-the-loop-checkpoints · Lesson: Loop Structure & Orchestration

Termination and Convergence

Convergence detection

Replacing intuition-based stopping with a mechanical criterion: monitor observable signals across refinement passes and stop when further passes yield diminishing returns. It fills the gap for prose, specs, and design tasks where no test harness exists; for code, PASS/FAIL from tests is the gate instead.

Avoid: trusting convergence alone on high-stakes output — stable is not the same as correct; pair it with an external checker.

Source: convergence-detection · Lesson: Termination & Convergence

Convergence signal · change velocity, output size, content similarity

One of the three observable measures convergence detection tracks across passes — change velocity (the rate of modification), output size, and content similarity (the diff between consecutive passes). When all three converge simultaneously, stop; when any diverges, issues remain unresolved and more passes are warranted.

Source: convergence-detection · Lesson: Termination & Convergence

Five-pass blunder hunt

Running the identical critique prompt five consecutive times against the same output, so each pass surfaces issues the previous passes normalized over. A single critique produces false confidence; near-identical critiques on passes 4 and 5 mean content similarity has converged and the output is stable.

Source: convergence-detection · Lesson: Termination & Convergence

Oscillation / expansion / low-quality plateau

The three failure patterns that call for a restart rather than more passes: output alternating between two versions (oscillation), growing each pass instead of shrinking (expansion), or all signals converging while quality stays poor (low-quality plateau). Each signals a redesign, not another iteration.

Avoid: iterating harder on a plateau — converged-but-bad means the approach is wrong, not under-polished.

Source: convergence-detection · Lesson: Termination & Convergence

Max-round limit

A hard cap on iterations that backstops every loop as a cost fallback, independent of any progress-based exit. Convergence detection tells you where to set it or when to stop earlier; the cap catches the runaway when no other signal fires.

Avoid: treating it as a quality gate — it prevents runaway, it does not certify correctness.

Source: convergence-detection · Lesson: Termination & Convergence

The Go/No-Go Gate

Go/No-Go gate · loop ROI gate

The upstream decision of whether to convert a manual task into an automated loop at all — answered before any loop mechanics. A loop earns its cost only when four conditions hold simultaneously: task cadence at least roughly weekly, objective verification, an absorbable token budget, and real tooling that lets the verifier see ground truth. Fail any one and a single prompt session is cheaper forever.

Avoid: reading a passing score as an instruction to build — review capacity and plan economics can still make the loop the wrong call.

Source: agent-loop-go-no-go-gate · Lesson: Go / No-Go

Cost per accepted change

The operating metric for a running loop: cost per accepted, merged change — the unit that captures both the loop's throughput and the reviewer time it actually consumes. Tokens-spent and tasks-attempted both miss the reviewer-time leg; below roughly 55% no-modification acceptance, the loop is doing the review work it was meant to remove.

Avoid: measuring the loop in tokens or tasks — neither prices the review bottleneck the loop creates.

Source: agent-loop-go-no-go-gate · Lesson: Go / No-Go

Budgets and Runaway Guardrails

Runaway guardrails

The deterministic floors that halt a loop even when the model never chooses to stop — iteration caps, budget primitives, wall-clock limits, and stuck-loop detection. They are a belt to the model's own stopping judgment, not a replacement for it: a budget that binds forces discipline; a budget that never binds is decorative.

Lesson: Runaway Guardrails & Stuck-Loop Recovery

Loop budgeting

Two independent decisions, not one: which primitive caps the loop, and how the budget is allocated across turns within that cap. The Go/No-Go gate decides whether to loop; loop budgeting decides how to bound it. One binding primitive beats three slack ones.

Source: loop-budgeting · Lesson: Runaway Guardrails

Budget primitive

The cap that fires first — iteration count (portable across model versions), token or cost budget (needs re-tuning on every model upgrade), or wall-clock (right only when latency SLOs bind harder than spend). The controller's real primitive is the pair (remaining_turns, remaining_tokens) exposed every step.

Avoid: a flat per-turn token cap on a single-session loop — accumulated context makes late turns several times more expensive, so the cap mis-prices them. Budget across the whole loop.

Source: loop-budgeting · Lesson: Runaway Guardrails

Reasoning sandwich

The canonical front-loaded allocation — extra-high planning, high execution, extra-high verification — concentrating compute where ambiguity is highest because planning errors propagate through every later turn and missed verification fails silently as success. It beats uniform high compute (66.5% vs 63.6% on Terminal Bench 2.0) when the phases are clean, and ties or loses when they are not.

Avoid: the sandwich on exploratory debugging — interleaved phases degrade it to noisy uniform compute plus routing overhead.

Source: loop-budgeting · Lesson: Runaway Guardrails

Stuck-loop recovery

What the harness does once a detector says "stuck" — a discipline separate from detection, because the cheap fix that breaks a repeater fails on a wanderer, and human handoff is a poor first choice when a single nudge would suffice. Detection catches the stuck agent; recovery escapes it.

Source: stuck-loop-recovery · Lesson: Runaway Guardrails

Recovery ladder

The bounded escalation a stuck loop climbs — nudge, replan/reflect, escalate model or effort, context reset from a progress file, human handoff, abort with logged failure. Each rung is a strictly larger perturbation of the agent's policy; you climb one at a time to find the cheapest rung that breaks the fixed point.

Avoid: jumping straight to context reset — it wipes load-bearing in-context state unless that state was already externalised.

Source: stuck-loop-recovery · Lesson: Runaway Guardrails

Progress metric

A measure that can only rise when real work is done — failing tests resolved, unique sources gathered, checklist items completed — used to separate a stuck loop (metric flat while activity continues) from one converging slowly (metric rising, even by small increments).

Avoid: activity proxies — API calls, file edits, log volume rise during a stuck loop too, so they cannot tell the two apart.

Source: stuck-loop-recovery · Lesson: Runaway Guardrails

Three stuck shapes · repeater / wanderer / looper

The shapes a stuck state takes, each with its own recovery move: the repeater (same action, same result — nudge toward a different approach), the wanderer (activity continues but nothing connects to the goal — reassess the goal), and the looper (alternates between a small set of actions — context reset). Identify the shape before choosing the move; wrong-shape recovery makes things worse.

Source: stuck-loop-recovery · Lesson: Runaway Guardrails

Iteration-cap backstop

A hard maximum iteration count per conversation that catches everything pattern detectors miss — unproductive iterations that differ each time and so never trip a repeat-detector. It pairs with shape-based recovery as defence-in-depth, and it bounds the recovery process itself so the harness does not build a recovery-loop on top of the original loop.

Source: stuck-loop-recovery · Lesson: Runaway Guardrails

The Outer Discipline

Loop engineering

The discipline of stacking outer loops — verification, scheduling, hill-climbing — around the inner agent loop so the human stops being the throughput ceiling. It composes outer loops around whichever inner-loop context strategy you chose, and sits one floor above harness engineering rather than replacing it; the two disciplines stack.

Avoid: conflating it with per-turn context strategy — that is the loop strategy spectrum; loop engineering operates a layer up.

Source: loop-engineering · Lesson: Improvement & Flywheel Loops

Bottleneck migration

The causal mechanism behind loop engineering: the inner loop produces output faster than a human can prompt the next task, so the human becomes the throughput ceiling — and each outer loop removes one place the human used to sit. Loop 2 replaces human grading, Loop 3 replaces human initiation, Loop 4 replaces human harness-tweaking.

Avoid: assuming the bottleneck disappears — it migrates to review bandwidth, which a loop multiplying output by N can lengthen rather than relieve.

Source: loop-engineering · Lesson: Improvement & Flywheel Loops

Flywheel / outer loop · hill-climbing loop

The outermost loop, where an analysis agent reads production traces and rewrites the harness — the return arrow that does not just loop back to the top but reaches inside and updates the inner loops directly, so each cycle makes them more effective. Its risk is drift: a harness optimised against yesterday's traces silently degrades when the task distribution shifts.

Source: loop-engineering · Lesson: Improvement & Flywheel Loops