🛠️ Building your first loop

Choose something where “done” can be checked independently of your opinion: tests pass, the format matches, the script runs without errors.

For your first loop, narrow it down to something with a built-in checker—that’s what makes the loop converge instead of wander.

Open-ended task × task with a checker; verifiable done state.

One sentence: "Every test in /tests passes when you run npm test." It becomes the loop’s done-state.

A vague objective ("clean this up") gives it no clear endpoint; the loop doesn't know when to stop.

Objective in one sentence; checkable × vague.

Allow edits to /src and /tests + running tests; NO merge or deploy permissions on the 1st run. The worker opens a PR, and a human merges it.

“Guardrails are the real work, not the agents.” Broad permissions too early = irreversible mess.

Permissions, guardrail, PR (pull request).

Ask it to write progress to PROGRESS.md and commit after each significant change, so you can pick up where you left off.

Anthropic’s harness: read state → incremental progress → self-verify → commit → leave things clean.

PROGRESS.md, commit, resume between sessions.

Gather context → make 1 change → verify (run tests) → repeat. ONE change per round is deliberate.

"Working on one feature at a time" was critical in the research; one change per iteration makes the loop converge.

4-step cycle; iteration granularity.

“Stop when all tests pass, or after 10 attempts, whichever comes first.” The SDKs provide max_turns.

Without a stop, you risk "bizarre emergent behavior" and a token bill that keeps growing.

Hard stop, max_turns, attempt cap.

Watch the 1st run live; fix the INSTRUCTIONS, not the output. When it fails, fix the failure domain and put it back in the loop.

Huntley: "clay on the pottery wheel" — you shape the prompt, not the piece one at a time.

Tighten the prompt; observe the run; the full 7-step loop.

A complete prompt: goal (tests pass), 4-step loop, PROGRESS.md + commit, hard stop at 10, and what not to touch.

It's the template you adapt for everything. Paste, run, observe.

Pasteable loop; objective + block + how to verify.

Same setup, different task: rewrite a paragraph until it’s under 50 words AND mentions the price.

The check is Functional—it checks the rules (counting words, finding "price"), not whether it reads well.

Loop outside of code; Functional check; 5-attempt guardrail.

Together, /goal and /loop create a loop that directs and ends itself based on the stated objective.

E.g., generate 10 concepts, score them using a rubric, then iterate on the best one until it reaches score X.

/goal, /loop, self-directing, self-terminating.

Add to the prompt: "Pause and ask me before deleting, sending, or paying for anything."

It's the “You-decide” check: irreversible actions go through you before they happen.

Human checkpoint; irreversible action; approval.

Read the state from PROGRESS.md, make progress on ONE feature, self-verify, commit with a note, leave things clean, repeat.

It's the loop that survives between sessions and doesn't repeat itself when the context fills up.

Externalized state; commit with a note; clean working tree.

Swap the checker (Functional → Visual with a screenshot, or Judgment with a second agent) and swap the domain.

The shape of the loop stays the same; mark the parts you swap out and reuse it for any task.

Functional × Visual × Judgment; blank template.

Define “done” in a way a machine can verify, not “make it good.”

Without a checkable done-state, the loop has no way to know it's finished.

Done-state; machine verification.

Maximum number of attempts, budget, or time. Always.

It's what keeps the loop from running forever and wasting tokens.

max_turns; budget; time limit.

The actions the agent takes need to be reliable and clearly described.

A poorly described tool makes the model use it incorrectly, and the loop turns into noise.

Clear description; reliable action.

Keep a history, but SUMMARIZE it so the context doesn’t bloat—one notes file.

A full context window makes the model lose track and cost more.

Summary; notes file; context window.

Generate → judge → fix → repeat. The maker never grades their own work.

The person who did the work is the worst judge of it; a separate checker keeps quality in check.

Maker → checker; evaluator-optimizer.

Large, multi-step job: ask for a plan before acting. Small job: skip the plan.

Planning everything is wasteful for a small task; not planning breaks a large one.

Plan before acting; when to skip it.

Save every thought, action, and result.

When the loop fails overnight, the log is the only thing that tells you what happened.

Thought/action/result trace.

Loops burn through tokens fast; start small and bounded, then scale up.

A loop without a cap or cost awareness becomes a billing surprise.

Start small and keep it limited; scale up later.

The loop acts, never checks, and confidently delivers something broken.

"Check your work" is the most underrated step of all.

Missing verification; confident nonsense.

“Improve the code” doesn’t provide a done state; the loop keeps spinning without a target.

A vague objective is the #1 cause of a loop that never "ends."

Vague × checkable; the loop’s target.

Beginners assume the model stops on its own; many loops (Ralph) have no model-side stopping condition.

Set a maximum number of attempts and watch the first run — the stop is yours, not the model’s.

Hard stop; Ralph; first-run supervision.

Trying to fix everything at once makes the loop struggle; one change per cycle converges.

Anthropic was explicit: "one feature at a time" was critical.

Granularity; one change per turn.

Letting the first loop merge, deploy, or delete = irreversible mess.

Scope the permissions; the worker opens a PR, it doesn’t merge it.

Permission scope; PR instead of merge.

Without progress + commits, a loop that runs beyond 1 context window forgets what it has already tried and repeats itself.

State on disk is what gives the loop memory across context windows.

Externalized state; context window.

Human-in-the-loop (approval gates) is supervision, not the agent’s cognition.

Don't copy an HITL guide expecting a loop build pattern.

HITL = human supervision; agent loop = cognition.

Handing full control to the loop and stopping reading the output — Osmani’s warning.

You remain the reviewer, especially at the beginning.

Human reviewer; don’t give up control.