---
name: justloopit
description: Turn a repetitive task into a self-correcting loop instead of doing it one prompt at a time. Interviews you, designs the loop (work list, unit, verifier, stopping rule), then writes a real verifier script, a runner, and a spec to disk. Use when the user says "loop this", "do all of these", "iterate over", "run this for every X", "batch", "keep going until", "enrich/migrate/audit/scrape all of Y", or is visibly doing the same task by hand for the Nth time. Do NOT use for a genuine one-off, or to run an already-designed loop on an interval (that is /loop).
license: MIT
metadata:
  author: Ian Muench
  version: 1.1.0
---

# justloopit

<role>
You design loops, not prompts.

The user has a task they are about to do N times. Your job is to replace "user
prompts agent, reads output, corrects, repeats" with a system where the
environment corrects the agent. You produce three artifacts and stop — you do
not run the loop.
</role>

<core_claim>
Agents are mediocre at knowing when they're done and excellent at reacting to
concrete failure output. A failing check is a better prompt than anything a
human would type, because it is specific and it is true.

So the leverage is never in wording the task better. It is in building something
that can say "no". **The verifier is the product. Everything else is plumbing.**
</core_claim>

---

## The four parts

Every workable loop has these. Three are easy; the third is the job.

| # | Part | Test of whether you have it |
|---|---|---|
| 1 | **Work list** | Can you enumerate it with code — no model call? |
| 2 | **Unit of work** | Can one agent with fresh context finish one item? |
| 3 | **Verifier that can fail** | Can it distinguish good output from bad *without* asking the model? |
| 4 | **Stopping rule** | Does the loop end without a human? |

<blocking_rule>
If you cannot state part 3 concretely, you do not have a loop — you have a
fan-out with extra steps, and it will launder bad work at scale.

Do not generate artifacts until part 3 is answered. The tell of a fake verifier
is a final step that amounts to "the agent said it was done." That is not a
check. See `references/verifiers.md` for how to find a real one, and the
soft-gate protocol for when none exists.
</blocking_rule>

---

## Procedure

### 1 · Understand the task before asking anything

Read what's in front of you first. Open the files, run the query, look at the
directory, check git log. Most of the interview answers itself — a question you
could have answered by looking is a question you shouldn't ask.

Specifically, find out:
- What produces the work list today (a query? a glob? a spreadsheet? their memory?)
- Has any of this been done already? **Existing completed work is your test
  fixture** — see step 5.
- What does "wrong" look like here, and who gets hurt by it?

### 2 · Interview — only the load-bearing gaps

Use **AskUserQuestion** if your harness has it, otherwise ask in plain numbered
questions with your recommendation first. Ask only where different answers change
what you build. Cap at 4 questions; prefer 2–3.

The four things you must end up knowing — derive what you can, ask the rest:

<interview_targets>
1. **Work list** — where it comes from, how big, and how you know it's complete.
2. **Unit boundary** — one row? one file? one URL? What makes two units independent?
3. **Verifier** — what must be true of a finished unit. Push for something
   mechanical. "It looks right" is not an answer; keep asking "how would a script
   know?"
4. **Stopping rule + blast radius** — retries before quarantine, batch size, and
   what must never happen (don't commit failures, don't delete source data,
   don't hit an API more than N/sec).
   If the work is open-ended (hunting bugs, sweeping, researching), offer a
   **spend cap**: "use a max of 1 million tokens." That is a real hard ceiling,
   unlike a percentage of a subscription, which nothing can read. See the
   spend-bounded section in `references/anatomy.md`.
</interview_targets>

Also ask **which direction of error is dangerous**. It sets severity, and it is
the question people skip. Overstating safety, over-reporting success, and
false-negatives on a security check are all worse than their opposites.

### 3 · Make the verifier real

Take the user's quality bar and turn it into assertions. `references/verifiers.md`
has the reframing table and a cookbook by task shape.

The move that unlocks most "unverifiable" tasks: **two independent descriptions
of the same thing can be cross-checked even when neither can be checked alone.**
A summary vs its source. A row-level flag vs its item-level tags. A migration's
output vs the old code's behaviour.

The second move: **persist the input.** A loop that reads something and writes
something can check the write against the read — but only if you kept the read.
This converts "don't fabricate" from an honour system into a `grep`.

If after honest effort there is no deterministic gate, follow the **soft-gate
protocol** in `references/verifiers.md` (adversarial multi-judge, majority must
fail to refute) and label it `SOFT GATE` in the spec, in those words.

### 4 · Choose the harness and say why

| If | Use | Why |
|---|---|---|
| Units need no agent at all | shell/node loop | Cheapest thing that works. Try this first |
| Units are independent and need an agent | subagent fan-out | Fresh context each, parallel |
| Multi-stage with per-item verify | `Workflow` (Claude Code) | Pipeline, no barrier between stages |
| Waiting on external state (CI, queue) | `/loop <interval>`, else cron | Polling the harness can't notify on |
| Units mutate the same files | worktree isolation | Otherwise they collide |

Details and runnable shapes: `references/harnesses.md`. State the choice and the
reason in the spec — a harness picked without a reason gets picked wrong. Two rows
name Claude Code features; on a harness without them, fall back to the shell runner
in `templates/runner.sh`, which needs nothing but bash. The artifacts are the same
either way.

### 5 · Dry-run the verifier against work already done

**Do not skip this.** Before the loop is trusted, run the verifier over output
that already exists. Every failure is a free bug report about work done by hand.

Then, when it reports something large:

<validate_first_run>
A suspiciously large count is a bug in the verifier until proven otherwise.
Pull 3–5 actual failing cases and read them before repeating the number to the
user. Expect to find one over-strict check on the first pass; that is normal and
finding it is the point of this step.
</validate_first_run>

### 6 · Write the artifacts

```
<project>/
├── scripts/verify-<thing>.<ext>   # the gate — exit 0 pass, 1 fail, 2 usage/env
├── scripts/run-<thing>-loop.sh    # work list → unit → gate → retry → quarantine
└── .loops/<thing>.md              # the spec
```

Match the project's language and conventions — read a neighbouring file first.
Templates and the verifier contract are in `templates/`.

### 7 · Hand over

Report: what the dry run found, how to run one unit, how to run a batch, what
you deliberately left to humans. Then stop. **You do not run the loop** — the
user reviews the verifier first, because a loop is only as trustworthy as the
check they haven't read yet.

---

## Rules for generated loops

<generated_loop_rules>
1. **Failure messages are prompts.** Every failure names the specific defect and
   what to do about it. `item-4.jpg is 1,204 bytes, not a JPEG — probably an
   error page` beats `image validation failed`. Write them to be fed back
   verbatim.
2. **Exit codes are the contract.** 0 = pass (warnings allowed), 1 = at least one
   failure, 2 = bad usage or missing environment. Never exit 0 on failure.
3. **Severity follows the danger, not the size of the diff.** The direction of
   error that hurts someone is a failure; the cautious direction is a warning.
4. **Never repair by weakening the check.** A loop that edits its own verifier to
   pass has inverted its purpose. Fixes go in the work, not the gate.
5. **Quarantine, don't commit.** After the retry cap, append the item and the
   reason to a quarantine file and move on. Failures never land.
6. **No silent caps.** If the loop truncates, samples, or skips, it says so in
   the report. Silent truncation reads as "covered everything".
7. **Fresh context per unit.** Prevents the last item bleeding into this one.
8. **Flaky I/O stays serial and small.** Browser automation, rate-limited APIs
   and photo fetches get modest batches, not maximum fan-out.
9. **The spec names what stays human.** Every loop has a residue the checks can't
   reach. Say what it is in the spec, in specific terms.
</generated_loop_rules>

---

## When not to build a loop

Say so plainly and stop:

- **Genuinely one-off.** Building the loop costs more than doing the task.
- **The work list can't be enumerated.** If you can't list it, you can't cover it,
  and you'll silently do a subset.
- **No gate is possible and the stakes are high.** A soft gate on a security
  finding or a medical claim is worse than doing it by hand, because scale plus
  plausibility is how bad output gets trusted.

Offer the nearest useful thing instead — often "let's build the verifier alone,
and you keep driving."

---

## Reference files

Load on demand, not upfront:

| File | Read it when |
|---|---|
| `references/anatomy.md` | Working out the four parts, or the user pushes back on the design |
| `references/verifiers.md` | Finding a gate — reframing table, cookbook, soft-gate protocol |
| `references/harnesses.md` | Choosing and writing the runner |
| `references/patterns.md` | The task resembles enrichment / migration / audit / scrape / research |
| `templates/` | Writing the artifacts (`verifier.mjs`, `runner.sh`, `spec.md`) |
| `examples/smoke-test.sh` | Confirming the templates still work after you edit one |