Iterate — refine to Done, don't stop at the first attempt
Trigger phrases: "iterate", "loop until done", "keep going until"
When
A task has an objective acceptance criterion (tests, a review gate, a spec) and the first attempt may not
meet it. This is a single-session refinement loop — NOT the harness /loop, which schedules a prompt on an
interval. Open-ended exploration with no checkable target does not belong here.
The loop
- Name the exit test first — the concrete, checkable condition that means "done": tests green,
review-agent-csk clean, the spec's acceptance criterion met, zero SonarQube findings. No exit test →
go to spec-planning first; a loop without a target never terminates.
Prefer an external, machine-grounded verifier — a test exit code, a schema match, a lint/quality gate —
over an LLM's self-assessment. A model grading its own output inflates; an "it looks done" or even a single
"review clean" with no objective check is a weak verifier. When the only available check is a judgment call,
ground it (a second agent with a distinct lens, an explicit rubric) rather than trusting the loop's own say-so.
For a generative task with no exit code, the eval-grader skill is that external verifier — a two-layer
scorecard (code metrics + LLM-judge) over a fixed set, read as signed deltas vs a pinned baseline.
- Run one round: change → verify (drive the real flow, not only tests) → check the exit test.
- Report the gap every round — state what still fails and why. Never loop silently.
- Repeat until the exit test passes. Stop early and surface it if: two rounds pass with no new
progress (you are stuck — report, don't spin), the exit test itself is wrong, or a blocker needs a
decision from the user.
- Close at the DoD gate, not at a commit.
commit-agent-csk still proposes and waits for §4.4
approval. The loop never commits, pushes, or deploys on its own.
Guardrails
- Bounded, not infinite. A fixed exit test plus a no-progress stop is the whole point; "keep trying
forever" is a bug, not diligence.
- Token discipline ([[token-budget]]): each round re-pays for context. Keep a round's output a summary,
push heavy logs to
docs/*.md, and don't fan out a subagent per round unless isolation demands it.
- Don't move the goalposts. Never weaken the exit test to end the loop — fix the work, or stop and ask.
1---2name: iterate3description: Refine-to-Done loop: repeat until tests green + review clean + nothing deferred; bounded. Not the harness /loop.4---56# Iterate — refine to Done, don't stop at the first attempt78<!-- routing-eval reads this line; it lives in the BODY so the always-on skill LISTING stays inside9 Claude Code's budget (1% of the context window) — an overflowing listing gets descriptions10 truncated or dropped, which strips the very keywords a match depends on. -->11Trigger phrases: "iterate", "loop until done", "keep going until"1213## When14A task has an objective acceptance criterion (tests, a review gate, a spec) and the first attempt may not15meet it. This is a single-session refinement loop — NOT the harness `/loop`, which schedules a prompt on an16interval. Open-ended exploration with no checkable target does not belong here.1718## The loop191. **Name the exit test first** — the concrete, checkable condition that means "done": tests green,20 `review-agent-csk` clean, the spec's acceptance criterion met, zero SonarQube findings. No exit test →21 go to spec-planning first; a loop without a target never terminates.22 **Prefer an external, machine-grounded verifier** — a test exit code, a schema match, a lint/quality gate —23 over an LLM's self-assessment. A model grading its own output inflates; an "it looks done" or even a single24 "review clean" with no objective check is a weak verifier. When the only available check is a judgment call,25 ground it (a second agent with a distinct lens, an explicit rubric) rather than trusting the loop's own say-so.26 For a generative task with no exit code, the `eval-grader` skill *is* that external verifier — a two-layer27 scorecard (code metrics + LLM-judge) over a fixed set, read as signed deltas vs a pinned baseline.282. **Run one round**: change → verify (drive the real flow, not only tests) → check the exit test.293. **Report the gap** every round — state what still fails and why. Never loop silently.304. **Repeat** until the exit test passes. Stop early and surface it if: two rounds pass with no new31 progress (you are stuck — report, don't spin), the exit test itself is wrong, or a blocker needs a32 decision from the user.335. **Close at the DoD gate, not at a commit.** `commit-agent-csk` still proposes and waits for §4.434 approval. The loop never commits, pushes, or deploys on its own.3536## Guardrails37- **Bounded, not infinite.** A fixed exit test plus a no-progress stop is the whole point; "keep trying38 forever" is a bug, not diligence.39- **Token discipline** ([[token-budget]]): each round re-pays for context. Keep a round's output a summary,40 push heavy logs to `docs/*.md`, and don't fan out a subagent per round unless isolation demands it.41- **Don't move the goalposts.** Never weaken the exit test to end the loop — fix the work, or stop and ask.
byerlikaya