loop-mode

name

loop-mode

description

Methodical feedback-loop harness — turn a goal into a Reason→Act→Observe→Check loop with a checkable done-criteria, real verification, a hard iteration cap, memory between passes, and a logged trail. Use when a task needs iteration to reach quality rather than a one-shot answer ("loop on this until…", "keep iterating until X", "run a goal loop", "set up a feedback loop", overnight/unattended goal runs, "build me X and make it actually good"). Invoke with /loop-mode <goal>. Composes with the built-in /loop, which supplies the cadence/trigger; this skill supplies the action and the stop-condition.

Loop Mode

Stop hand-prompting the agent through every revision. Hand it a goal, a way to check the goal, and a hard stop — then let it run Reason → Act → Observe → Check until done. This skill is the harness that makes that loop robust instead of a runaway.

A loop is three parts: a trigger, an action, and a stop condition. The built-in /loop owns the trigger (run every N minutes, or self-paced, including overnight). This skill owns the action and the stop condition — the part that decides what to change each pass and when to quit. The two compose: /loop overnight can fire a /loop-mode goal.

A loop is only ever as good as its done-check. Two pillars carry the whole thing:

1. A checkable goal — objective wherever possible ("tests green", "avg rubric score ≥ 9/10"), never "until it feels done".
2. Real verification — observe with an actual tool (run the build, run tests, open the browser and screenshot, score against a reference), not by asserting success.

Everything below exists to keep those two honest.

Gate: does this even need a loop?

Most tasks do not. A loop earns its cost only when iteration plus verification beats a single careful pass. Before framing anything, decide:

• Skip the loop when the task is one-shot and the check is trivial (rename, typo, a question, a small known edit). Say so and just do it.
• Run the loop when quality climbs across attempts and there is a concrete way to measure that climb (a UI that must look right, code that must pass a suite, a doc that must hit a rubric).

If a task wants iteration but has no checkable verification, that is the blocker — surface it and design the check first. A loop without a real done-check just burns budget at a plateau.

Phase 0 — Frame the LOOP SPEC (the contract)

Before any iteration, write the full spec. Use assets/loop-spec-template.md as the fill-in. Every field is mandatory; an unfilled field is a design hole, not a default.

• Goal — the target outcome from $ARGUMENTS + conversation, stated as objectively as the task allows.
• Done-criteria — the checkable stop condition. Push subjective → objective. If the goal is irreducibly subjective (taste, "looks right"), convert it to a rubric + threshold (e.g. "≥ 9/10 averaged over {clarity, contrast, fidelity}") and name who scores it. See references/loop-patterns.md for rubric design.
• Verification method + tool — how each pass is checked, naming the concrete tool: build command, test runner, linter, Chrome DevTools MCP screenshot, diff against a reference. "I'll review it" is not a method.
• Hard stop — a maximum iteration count and a time/cost budget. Always present so the loop physically cannot run forever. Default: 8 passes and ~2 hours wall-clock unless the task argues otherwise (so an unattended run never has to invent the budget).
• Topology — solo / maker-checker / manager-helpers (see below; default solo).
• Log path — where the iteration trail is written (default _loop/loop-<slug>.md at project root).

Adaptive approval

• Interactive session → present the LOOP SPEC and wait for an explicit go before iterating (Plan → Approve → Execute). The user may edit the spec.
• Unattended (fired via /loop, a scheduled run, or autonomous-loop) → do not ask. Fully resolve every spec field from available context, log the resolved spec, and start. If a mandatory field cannot be resolved without a human, stop and write the blocker to the log rather than guessing.

Phase 1 — Plan first

Reason about the approach before the first action: the likely path to the goal, the riskiest unknown, and what the first pass should attempt. Cheap planning here prevents expensive thrash later. Write the plan as iteration 0 in the log.

Phase 2 — The loop

Each pass is four steps, logged as one block:

1. Reason — given the last observation, decide the single most valuable change to make this pass and why. Do not repeat an approach the log already shows failed.
2. Act — implement that change. Keep the diff small and reviewable.
3. Observe — run the verification method and capture real evidence: test output, the screenshot, the rubric score, the error. Evidence is recorded, never asserted.
4. Check — compare evidence against the done-criteria.
   • Met → stop, go to Phase 3.
   • Hard cap or budget reached → stop with the best result so far, go to Phase 3.
   • Otherwise → log the pass and loop.

Memory between passes is the point. The log is working memory: pass #, change made, observed result/score, decision. Read it before each Reason step so the loop accumulates instead of circling.

No-progress detector. If the measured result fails to improve for K consecutive passes (default K=2), stop early — a plateau means the current strategy is exhausted. Report the plateau and the best result; do not grind to the hard cap for nothing. (Rationale and interactive handling: references/loop-patterns.md §5.)

Phase 3 — Stop and report

End with a tight report:

• Why it stopped — done-criteria met / hard cap / budget / plateau.
• Final state — what was produced and its final score or check result.
• Iteration trail — the per-pass log (or a link to it), showing the climb.
• Human-check list — what a person should still eyeball, especially anything the verification could not cover.

Loops get you much closer on the first try — they do not guarantee 100%. Name the residual gap honestly.

Topology — pick the lightest that works

Default to solo. Escalate only when the check demands independence. Full patterns and wiring are in references/loop-patterns.md.

• Solo — one context reasons, acts, observes, repeats. The default; right for objective checks (build/tests) and most visual loops.
• Maker-checker — a separate checker sub-agent grades the work in a fresh context and returns score + specific feedback. Use when the done-check is subjective or when self-grading is unreliable. This is the "dedicated scorer" lesson; wire it like ask-the-board — spawn the checker as an independent Agent. The leniency rationale and the one-time calibration step are in references/loop-patterns.md §1.
• Manager-helpers — the goal splits into parallel sub-goals each with its own loop; one orchestrator coordinates. Fan out with parallel sub-agents (the Agent/Task tool, or the Workflow tool where available); reserve for genuinely decomposable work.

Verification recipes (summary)

Detailed, copy-ready recipes for each task type live in references/loop-patterns.md. In brief:

• Code / build / tests — edit → build → test → lint → parse failures → fix. Done-criteria is objective: build green, suite passing, no new lint/regression. Lean on test-driven-development and debugging-and-error-recovery. (iOS is human-in-the-loop here: edits happen on Windows, the build runs on the Mac, and the observe step is the pasted-back compiler output — see the reference.)
• Frontend / visual UI — render → screenshot via the Chrome DevTools MCP (browser-testing-with-devtools skill) → compare against a reference image or score against a visual rubric → fix. Capture the screenshot every pass; the climb must be visible. This is the closest analog to the thumbnail / Abbey-Road style demos.

Guardrails / red flags

• A done-criteria of "until it's good" or "until satisfied" — convert it to a metric or a rubric+threshold before starting.
• No hard cap, or a cap with no budget — the loop can run for hours with no payoff.
• "Observed" results with no captured evidence — that is asserting, not verifying.
• The same failed change reappearing across passes — the log isn't being read.
• Reaching for manager-helpers when solo would do — pay for independence only when the check needs it.
• A loop running unattended that hits a missing-info wall and guesses instead of stopping.
• Looping a task that never needed a loop (failed the Gate).

Resources

• references/loop-patterns.md — topologies in depth, the dedicated-scorer pattern, subjective→objective rubric design, full code and visual verification recipes, worked examples on this stack (Blazor, C#, iOS, SQL), cost management, and anti-patterns.
• assets/loop-spec-template.md — the fill-in LOOP SPEC contract; copy it into the log to start a run.

Verification (of this skill's own run)

• A complete LOOP SPEC was written before the first action (no blank mandatory fields).
• The done-criteria is checkable — a metric, a passing check, or a rubric+threshold — not "until good".
• The verification method names a concrete tool, and real evidence was captured every pass.
• A hard cap and a budget were set and respected.
• An iteration log exists showing per-pass change → result → decision.
• The loop stopped on done-criteria, cap, budget, or plateau — and the report says which.
• In interactive mode the spec was approved before iterating; in unattended mode it was fully resolved and logged, with blockers stopping rather than guessing.