<!--
Iterative Dev Loop
Part of the Bles Software agent skills repository:
https://www.bles-software.com/claude-skills

Install for Claude Code:
  mkdir -p ~/.claude/skills/iterative-dev-loop
  mv iterative-dev-loop.md ~/.claude/skills/iterative-dev-loop/SKILL.md

Install for Codex:
  mkdir -p ~/.codex/skills/iterative-dev-loop
  mv iterative-dev-loop.md ~/.codex/skills/iterative-dev-loop/SKILL.md

For Gemini CLI and other agents, drop the body of this file into the
project instruction file the agent already reads.
-->

---
name: iterative-dev-loop
description: >
  The default multi-round quality loop for development, build, visual, and any
  non-dev task with a checkable output. Instead of shooting once, iterate in
  rounds: change, run/render, verify the REAL result, compare to the previous
  round, keep only clear wins, log each round, and stop at a plateau or the
  goal. Use automatically on dev/visual/quality work where the verifier is cheap
  (render, screenshot, test, lint, speed, eval score) and iteration is safe
  (revertible / worktree). Do NOT use for slow- or uncontrollable-feedback goals
  (SEO rank, brand awareness, multi-month churn) or when there is no honest
  checkable signal — one careful pass is enough there.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# Iterative Dev Loop

One careful shot is the floor, not the ceiling. When the output can be checked
cheaply and iteration is safe, keep raising the bar round by round until it
stops paying off.

## When it fires (default-on)

All three must hold, or skip the loop and do one careful pass:

1. **Objective-enough check** — a real signal you can read after each round:
   rendered screenshot, passing test, lint clean, load time, eval score, or a
   like/unlike visual comparison against the previous round.
2. **Fast feedback** — minutes, not weeks. Render/test/measure now, not "wait
   for SEO to move".
3. **Safe, revertible iteration** — a git worktree, a branch, or a file you can
   restore. Anything irreversible in production stays approval-gated and out of
   the auto-loop.

Skip it for: trivial one-line changes, pure chat, and goals with slow or
uncontrollable feedback. Don't force rounds where there's nothing honest to
measure.

## The loop

```
round 0  → build the first working version. Verify it REALLY works
           (render it, run the test, measure it). This is your baseline = 100.
repeat:
  round n → make ONE focused improvement aimed at the weakest thing you saw.
            Run/render/measure again on the SAME check.
            Compare to the previous round.
            Keep the change ONLY if the improvement is clear and obvious
              (a clean win, not noise). Otherwise revert it.
            Log the round: what changed, the before/after signal, kept or reverted.
  stop when: ~2 rounds in a row with no clear win (plateau), OR the goal/target
             is met, OR the round cap / token budget is hit.
```

Raise the bar each pass: treat the last kept version as 100 and push for a
clearly better result, not a cosmetic diff. Small ambiguous wins are noise —
only keep what's obviously better, so the loop stays safe to run unattended.

## Verify the real thing (state = 1, not "should work")

The comparison is only as good as the check. Look at the actual rendered
output, not the source or the logs:

- **UI / web / landing / dashboard**: render the page, screenshot at mobile and
  desktop, inspect for clipped text, overlap, missing elements, broken spacing,
  weak hierarchy, blank sections, unprofessional polish. Fix and re-render.
- **Code / logic**: run the test or a real request; read the result, not the
  exit code alone.
- **Speed / size**: measure the number (ms, bytes, tokens) before and after.
- **Doc / slide / image / prompt** (non-dev with checkable output): render it,
  read/inspect it as a strict reviewer, compare to the last round.

Never claim "checked visually" or "improved" without having opened the rendered
result of THIS round.

## Safety and caps

- **Worktree / branch for auto-iteration.** Reversible by construction. Land the
  winner back on the working tree at the end.
- **Round cap + token budget.** Name them up front (e.g. up to 4-5 rounds).
  `# ponytail: hard round cap, raise only if a round is still clearly winning`.
- **Production-irreversible stays approval-gated.** Deploys, sends, payments,
  destructive ops are never inside the silent loop — finish the loop locally,
  then surface for the one approval the domain rules require.
- **Log the pass.** A short per-round line (changed / signal before→after /
  kept-or-reverted) so the run is auditable and the plateau is visible.

## Report

End with the winner and the trail: baseline → each kept round with its signal →
why it stopped (plateau or goal). Short. The kept diff is the deliverable; the
log proves it's an honest win, not a vibe.

## Relation to existing gates

This is the multi-round wrapper over two bricks you already have:
- the verify-until-it-really-works loop (change → run → verify → confirm), and
- the `reviewing-visual-output` gate (render, inspect, fix before delivery).

Those are single-pass. This skill runs them round after round, keeping only
clear wins, until the number stops moving. Reach for `reviewing-visual-output`
for the visual-check details; reach for `autoresearch-machine` instead when the
target is ONE digital asset against ONE slow-but-objective business number
(CTR, reply rate, conversion) rather than a dev/quality output you check now.