Loop terms & pattern cheat sheet

This glossary defines the vocabulary used across the /learn guides and the /loops templates. Terms are grouped by domain; anchors are the kebab-case names so guides can deep-link. The table at the end maps each pattern to its typical trigger, its known risk, and the check that catches it.

Core concepts

ai-loop

A control loop around a model: trigger → context → act → verify → escalate, with state, permissions, stop conditions, and a check on the result. A model call is a component; a loop is the working system.

scheduled-prompt

The same instructions on a timer. No state, no check, no stop rule. The starting point a loop upgrades.

workflow-vs-agent

Anthropic's distinction: workflows orchestrate LLMs and tools through predefined code paths; agents dynamically direct their own process and tool usage. Production systems usually blend both — a deterministic outer workflow with adaptive inner steps.

trigger

What starts a loop: a user request, cron schedule, webhook, CI failure, new issue, stale content check, or feed update. Declared in the manifest's trigger field; the trigger is a contract, not the scheduler implementation.

context-assembly

The step where a loop loads docs, repo state, memory, tickets, web sources, or APIs into the model's context for the turn. A designed artifact, not a default; bad context assembly looks like model failure.

tool-call

An invocation of an external capability (a search, a file edit, a command, an API) by the model during a loop step. The tool surface is part of the harness, not the model.

observation

The captured result of a tool call or step — command output, test results, web data, reviewer comments, errors — fed back into the next step of the loop.

verification

The check that the loop's output meets explicit success criteria. Verification is the actual product: the gap between "it ran" and "it worked" is where loop projects die; see How you know it worked.

escalation

The act of stopping a loop and surfacing ambiguity or a boundary condition to a human or reviewer with context, rather than guessing. See escalate-dont-guess.

state

Durable memory of what was tried, what passed, what failed, and what needs a human. State is the spine of a loop — without it, a loop re-does work and re-alerts endlessly. Declared in the manifest's state.paths.

harness

The assembly around the model — tools, prompts, context, memory, verification hooks, guardrails — that does the actual work. The harness is the agent; the model is one component; see The harness: what actually does the work.

audit-trail

The dated, evidence-linked record of what a loop did: what changed, evidence, recommended action, confidence and risk, and whether it acted autonomously or needs approval. The five-part report is the minimum viable audit trail.

run-log

The machine-readable record a loop publishes after each run: what changed, evidence, recommended action, confidence and risk, and whether it acted autonomously or needs approval. On human-facing surfaces we call these run notes — the same files, the plain name a reader sees. See audit-trail for the five-part report shape and five-part-report for the fields. Loops rot: maintenance is part of the design shows where run notes fit.

Patterns

react-loop

Reason, call a tool, observe, repeat. The foundational agent pattern; combines reasoning traces with actions so the model can interact with environments and update behavior from observations (/resources#react-paper).

plan-execute-verify

Decompose work into steps, execute, and verify each against criteria. Risks an expensive bad plan; mitigated by a test or checklist per step.

evaluator-optimizer

A generator proposes, an evaluator critiques, the loop improves. Self-evaluation is too lenient when the same agent grades its own work; mitigated by a separate evaluator or deterministic tests (/resources#anthropic-building-effective-agents).

reflection

Convert failure feedback into verbal memory for the next attempt. Can preserve bad lessons as easily as good ones; needs an external reward, test, or result signal before it is trusted (/resources#reflexion-paper).

orchestrator-workers

A planner splits work across specialist workers, then synthesizes results. Benefits are context and risk isolation per subtask; costs are coordination overhead and duplicated work.

watchdog

A monitor loop that polls a source (RSS, API, logs, CI) and reports or acts on changes. Risks alert spam or stale polling; mitigated by change detection, rate limits, and no-action-on-empty.

ci-repair-loop

Detect failing checks, inspect logs, patch, and rerun. Risks fixing symptoms and masking the real issue; mitigated by green CI plus diff review.

content-freshness-loop

Find outdated docs, dead links, or new sources on a schedule. Risks churn and low-value edits; mitigated by source-backed diffs and a human publish gate.

agent-usability-test

Have an agent follow docs or templates in a clean environment and report friction. Risks a false pass if the environment isn't clean; mitigated by a fresh checkout or container with a committed transcript.

self-maintenance-governor

Audit system failures and create improvement tasks with human gates. Risks over-optimizing itself without a product signal; mitigated by a human-governed backlog and measurable failure reduction.

Safety & governance

autonomy-scope

The useful question is never "autonomous or not" but which actions are autonomous, which are proposed, and which are forbidden. Autonomy is scoped, not binary; see When a loop must stop and ask you.

human-gate

A condition that must stop for human or reviewer approval before acting — public publishing, credential changes, spending, destructive or irreversible actions. Declared in the manifest's human_gates.required_for; a gate that lives in prose but not the manifest does not exist.

allowed-and-forbidden-actions

The manifest declares allowed actions and forbidden ones explicitly — destructive vs reversible, credential scope, spend limits, data exposure. The forbidden list is what makes the allowed list credible.

credential-scope

The least-privilege set of credentials a loop needs, declared by name in the manifest. Values never appear in the manifest; a reviewer audits scope before install.

stop-condition

A declared limit that tells a loop when to stop: step limits, timeouts, retry caps, no-action-on-empty, escalate-after. A loop without stop conditions is a runaway with a schedule.

budget

A cap on what a loop may consume — steps, time, spend, tokens. Related to stop conditions; a loop that exceeds its budget escalates rather than continues.

rollback

The ability to undo a loop's last run before granting the next one. Prefer proposals (PRs, cards) over direct mutation; know how to undo before you automate.

escalate-dont-guess

When a loop hits ambiguity outside its declared scope, the correct move is to stop and surface it with context, not to pick a plausible action (docs/SELF-MAINTENANCE-BRIEF.md); see When a loop must stop and ask you.

maker-checker

The agent that produced work must not be its only verifier. The self-evaluation trap is agents over-crediting their own output; mitigated by a separate evaluator, a deterministic check, or a human.

clean-room-run

The strongest doc/template verification: a fresh environment, an agent given only the published docs, a committed transcript. False passes come from dirty environments; see How you know it worked.

Operations & artifacts

loop-manifest

A loop.yaml file declaring what a loop needs, may do, must verify, and when it must escalate. Backend-agnostic; validates against spec/loop.schema.json. Field definitions at /spec.

verification-status

A template's status — verified, draft, or stale — computed from evidence files, never hand-set. Verified requires a clean-room run with a committed transcript; statuses auto-decay to stale after a freshness window without a green run; see How you know it worked.

five-part-report

The minimum viable audit trail a loop emits: what changed, evidence, recommended action, confidence and risk, and whether it acted autonomously or needs approval.

dedupe-state

Durable state used to suppress findings already surfaced in prior runs. A loop without dedupe state re-alerts endlessly; run 2 should never repeat run 1's findings.

loop-rot

The silent decay of a previously working loop: APIs change, models drift, docs go stale, credentials expire, state files bloat, boards fill with duplicates. Last month's green run proves nothing about today; see Loops rot: maintenance is part of the design.

---

Pattern reference

The pattern cheat sheet maps each shape to the trigger it usually serves, the risk it brings, and the check that catches that risk. Pattern names link to the term anchors above.

Pattern	What it does	Typical trigger	Key risk	Verification
ReAct / tool loop	Reason, call a tool, observe, repeat.	User goal or agent subtask.	Runs too long or takes unsafe action.	Tool output + stop condition.
Plan → execute → verify	Decompose work, execute steps, verify against criteria.	Implementation, research, ops task.	Bad plan becomes expensive.	Test/checklist per step.
Evaluator–optimizer	Generator proposes; evaluator critiques; loop improves.	Writing, code, data extraction, plans.	Self-evaluation is too lenient if same agent grades.	Separate evaluator or deterministic tests.
Reflection / Reflexion	Convert failure feedback into verbal memory for next attempt.	Repeated attempts, coding, reasoning, benchmarks.	Reflection can preserve bad lessons.	External reward/test/result signal.
Orchestrator–workers	Planner splits work across specialists, then synthesizes.	Research, coding, audit, multi-file changes.	Coordination overhead, duplicated work.	Parent/child dependencies + final synthesis.
Watchdog / monitor loop	Poll a source and report/action on changes.	Schedule, RSS, API, logs, CI.	Alert spam or stale polling.	Change detection + rate limits.
CI repair loop	Detect failing checks, inspect logs, patch, rerun.	CI failure, PR update.	Fixes symptoms; masks real issue.	Green CI + diff review.
Content freshness loop	Find outdated docs, dead links, new sources.	Daily/weekly schedule.	Churn and low-value edits.	Source-backed diff + human publish gate.
Agent usability loop	Have an agent follow docs/templates in clean env.	Release, template update.	False pass if environment not clean.	Fresh checkout/container transcript.
Self-improvement loop	Audit system failures and create improvement tasks.	Schedule, incidents, task outcomes.	Over-optimizes itself without product signal.	Human-governed backlog + measurable failure reduction.

Sources

• docs/research/loop-landscape.md — the landscape report behind the pattern cheat sheet.
• /resources#anthropic-building-effective-agents — workflow-vs-agent and orchestrator-workers patterns.
• /resources#react-paper and /resources#reflexion-paper — foundational loop patterns.