# Ratchet Loop Generator — instructions for an AI agent You are reading this because someone asked you to help them fill in the brief at **https://ratchet.babzlabz.com**. That page turns a brief into a long copy-paste prompt for a self-improving build loop, plus a downloadable run kit. Your job is to produce **field values they can paste**, not to run the loop yourself. Output each field under its own heading, verbatim and ready to copy. Do not add commentary inside a field value. --- ## The one thing to get right The loop's output can only be as good as the **bar** — the real thing it compares itself against. A brief with a strong goal and no bar produces a loop grading its own homework. Spend your effort there. --- ## 01 · The goal — required, the only required field **What it needs:** what the finished thing must *achieve*, in plain prose. No length limit; nothing is ever truncated. **Rules:** - Say what it must **do**, not which tools to use. Naming the stack caps the result at what the person already imagined. - Prefer statements someone could **check**. "60 fps during a mid-game fight with a live base and an enemy army" is checkable; "fast" is not. - Anything you cannot attach a number or an observation to will be judged by taste, which is fine — but say so deliberately rather than by accident. - Name what it must **not** be, if there is an obvious wrong answer. Negative anchors work. **Formatting that changes behaviour:** the tool counts list items in the goal to guess how many separate parts the project has. **More than about three bullet points selects the Ratchet tier**, which costs roughly 10–16× per promoting round. That is correct for a large multi-part project and wasteful for a small one. If the work is really one piece, write prose instead of a bulleted list, or set the tier explicitly in field 04. --- ## 02 · The bar — what does good look like? **What it needs:** one or more references the agent can actually open and hold up beside its own work. Every reference must be **named** (a specific thing, not a category), **fetchable** (openable by an agent that is not on this machine), and **comparable** (close enough in kind that beating it means something). **Four kinds, and the tool detects which you gave it:** | Kind | Use it for | Notes | |---|---|---| | A web link | A live site, a page, **a direct image file** | The tool screenshots it desktop + mobile and saves the page text | | A typed path | Files already in the repo | **Prefer relative** — `refs/` or `./refs/hud.png`. An absolute path like `C:\refs` only works if the agent runs on that machine | | An uploaded file | Anything shared with a team | Becomes a web link any agent can open | | A few words | When there is no artifact, only a standard | Honest, and weaker — say so | **You may paste a whole list.** The field accepts a block of text and extracts every `http`/`https` URL in it, ignoring the prose around them. One URL per line, a markdown bullet list, or a comma-separated row all work. Captures then run one at a time, because the browser service allows one call every ten seconds. ### Reference rules learned the hard way — apply these 1. **Direct image files beat gallery pages.** Galleries lazy-load, so a screenshot of one often shows blank thumbnails. Link the `.jpg`/`.png` itself. 2. **Some sites serve a bot check instead of the page.** Large commercial databases behind Cloudflare commonly return a "Verify you are human" interstitial to an automated browser. That interstitial screenshots perfectly and is worthless as a bar. The tool now flags these as **"not the page"** — if you see that, replace the reference. 3. **A gallery directory often 404s while the files under it serve fine.** If `/gallery/thing/` fails, try `/gallery/thing/Shot01.jpg`. 4. **A live app is capturable, but differently.** Anything with a render loop — a game, a canvas, a socket dashboard — never goes network-idle. The tool retries such pages on `load` with a settle wait, so they work; the capture just takes a few seconds longer. 5. **A site root is a weak reference.** It serves whatever was published last. Link the exact page being judged against. --- ## 03 · Where it runs **Values:** `Claude Code` or `Grok Build`. Ask which they use; do not guess. The emitted prompt differs substantially between them — spawn syntax, capability modes, which models can be used for judging, and which failures are silent. Getting this wrong produces a prompt full of instructions the harness cannot execute. --- ## 04 · Loop strength — three tiers, each adding to the one before | Tier | What it adds | Cost | Use when | |---|---|---|---| | **Gauntlet** | Build, get judged by a fresh critic, fix, repeat | 1× | Short and cheap, or a single round | | **Duel** | Keeps the best round instead of the last; tracks which situations nobody tested | ~3× | **Most work. This is the default** | | **Ratchet** | Also re-tests everything that already passed, every round | ~10–16× | Long runs, many separate parts | Leave it alone unless you have a reason: the tool picks a tier from the brief and prints a line saying why. Choose **Ratchet** only for genuinely long, many-part work — measured on a short single-part job, its extra machinery caught nothing and the plain loop reached a comparable result for a fraction of the cost. --- ## 05 · Caps — optional, and you should **Two fields:** a token budget and a maximum round count. Plain integers. - **Leave one blank and the prompt says so in words**, and forbids the run inventing a limit of its own. That matters: a run left blank once read "set a maximum round count", chose 8, and stopped there while its author expected thirty. - A Ratchet run wants **25–30 rounds** to be worth its price. - A token cap does **not** squeeze the work into the budget. The run goes at full speed and stops when the money is gone, so you get **fewer improvements, not a half-built thing** — and the prompt tells it to stop before starting a round it cannot afford to finish, then hand back the best version with a note saying it ran out rather than finished. --- ## 06 · What must always be true — optional, and worth more than the rest **What it needs:** one sentence naming something that must never break, and what would prove it. Plain words; the agent works out how to test it. Or upload a script, which is stronger because nothing about it is open to interpretation. The upload takes any plain-text file up to 256 KB — `.mjs`, `.js`, `.sh`, `.ps1`, `.py`, `.txt` — and ships it inside the run kit under its own name, to be run exactly as it is. It must exit non-zero when the property is broken; that exit status is the whole check. **This is the only part of the run the loop cannot reword.** Everything else it checks, it decided on by reading the brief. **Formatting rules:** - **One property per entry.** Do not join two with "and" — a single check testing two unrelated things cannot tell you which half failed, and the validation machinery tests one property at a time. Two properties means two entries. - **Make it enumerable.** "Every control in the UI does something" cannot be checked without a list of controls. Name the list, or name a specific control and a specific observable. - **Binary beats subjective.** "The repository contains no `.png`, `.jpg`, `.mp3` or `.wav` files outside test fixtures" is provable by one file scan. Prefer that shape. - Good: *"Selecting a sidebar item and placing the building changes credits, power and the building list."* - Bad: *"The HUD must work properly and there should be no external assets."* — two properties, and neither is enumerable. **Always checked anyway, whatever you write here:** no logged errors, the same result twice in a row, keyboard reachable, no third-party calls, and never slower or heavier than the first version was. --- ## Output format Give them this, and nothing else: ``` 01 GOAL 02 BAR 03 WHERE IT RUNS Claude Code | Grok Build 04 LOOP STRENGTH Gauntlet | Duel | Ratchet (or: leave to the tool) 05 CAPS tokens: rounds: 06 WHAT MUST ALWAYS BE TRUE ``` If you could not verify a reference is reachable, **say so next to it** rather than presenting it as good. A dead reference is worse than no reference, because the run spends real money before anyone notices. --- *The full method is at https://ratchet.babzlabz.com/method.html, and the complete specification ships as `RATCHET-LOOP.md` inside every downloaded run kit.*