Mechanism: Loop

Part of Mechanisms of Vibe Coding · Core · Read first: Goal, Constraints.

One-sentence definition

A loop is running the same goal-driven pass again — prompt, edit, check — until a defined stop condition holds, instead of treating one chat reply as the finish.

The problem

You ask the agent to fix a failing test. It edits, explains confidently, and stops. You run the test; it still fails. You paste the error again. It patches something else and stops again. You are the loop.

One-shot workflows assume the model gets it right first try. For real bugs, that wastes time. Each message without a fixed goal drifts the session: pass three fixes pass two’s mistake, not your task.

Symptoms:

• You send the same error output two or three times
• The agent says “fixed” but you have not re-run the check
• Ping-pong progress, not forward motion
• You wish the agent would “keep going until tests pass” — that is a loop, and it needs a stop rule

How it works

A loop has a fixed prompt template (goal + constraints), a work pass (edits), and a check (test, lint, or review). After each check: stop or run another pass with the same template plus new evidence (failure output, diff feedback).

  Loop prompt (goal + constraints)
       │
       ▼
  Work pass (edit)
       │
       ▼
  Check (test / lint / review)
       │
       ▼
  Stop condition met? ──no──► next pass (+ failure output)
       │
      yes
       ▼
     Done

Name the loop upfront: “Repeat until health.test.ts passes, max five passes.”

Ralph loop is the same pattern with automation: an outer script re-invokes the agent with a fixed prompt until a termination condition fires. The mechanism is still loop + stop rule.

When to use it

• Failing tests, type errors, or lint needing more than one edit
• Machine-checkable done conditions
• Local quality gates before commit
• Any task where you already re-prompted manually more than once

When not to use it

• Exploration with no check — loops without verify become churn
• Stop condition is “human likes it” — use checkpoint instead
• Same error every pass — stuck detection, not more iterations

Failure modes

Infinite loop — No cap or weak stop rule. Fix: Termination condition + max passes.

Checkless loop — Agent self-reports success. Fix: Verify loop with raw output.

Drifting prompt — Goal rewritten each pass. Fix: Same goal block; append only failure logs.

Wrong target — Tests pass but symptom remains. Fix: Stop on the goal’s verify line, not a proxy.

Manual fatigue — Hour of paste loops. Fix: Automate outer loop once the prompt template is stable.

Minimal example

Context: health.test.ts expects ok: true, gets false. Same goal and constraints as earlier Core articles.

Steps:

1. Loop contract at top of session:

   Loop: Fix until pnpm test -- health.test.ts passes.
   Max passes: 5
   Goal: GET /health returns { "ok": true } after startup.
   Constraints: only src/health.ts and src/bootstrap.ts; no new deps.

1. Pass 1: Agent edits → you run test → copy stderr only into chat.

1. Pass 2: Same loop block + failure output → agent edits → test again.

1. Stop when green or at five passes (then escalate: smaller goal, different model, human debug).

Done when: Test passes within max passes without changing the goal mid-loop.

Tool instances (optional deep-dive)

Portable idea above; tool-specific. Date: June 2026.

Cursor

• Manual loop: Same chat; same goal block; only verify output between passes.
• Automated loop: Goal + constraints in a prompt file the loop re-reads each iteration.
• Agent: “Continue the loop until pass or 5 iterations” only after goal and constraints are fixed in message one.
• Hooks: Post-edit test hook feeds the next pass — see hooks.

Other tools

Aider /run + fix, Claude Code retry scripts, CI re-run on failure — same shape.

Related mechanisms

• Termination condition — what stops the loop; read next in Core
• Verify loop — what to run between passes
• Stuck detection — when to break out instead of looping

Try it yourself

Exercise: Manual three-pass loop on one failing check: same goal block; you run verify after each pass; paste only failure output on pass 2 and 3.

Done when: Check passes, or you hit three passes and can say why it stalled (goal, boundary, or stuck).