--- name: cc-build-prompts description: "Write a coding-agent build prompt that carries its own answer key — front-loaded reasoning, numbered testable specs, embedded fire-tests with expected exits, a decision gate for the uncertain part, and an explicit output contract. Reach for it whenever you are tempted to write go build X and let me know." --- # High-Reward Build Prompts for a Coding Agent ## The one idea **Front-load the reasoning.** A high-reward session is one where every expensive decision — *what* to build, *how* to verify it, what the failure modes are, *when* to stop and defer — was made **before** the session and written into the prompt. The session itself is then pure execution plus falsifiable proof. That is the whole reason these prompts are fast, cheap in tokens, and safe to hand off: there are no clarification loops to burn tokens, and no judgment calls left to improvise. > **The delegable unit is the task that carries its own answer key.** Why this is *low-token* specifically: an under-specified task spends its budget on exploration, clarifying questions, and re-work. A fully-specified task with embedded tests spends its budget on building and proving. Same model, same problem — very different cost. The reasoning gets paid for either way; you choose whether it happens in the cheap place (your prompt, once) or the expensive place (the agent's session, repeatedly). ## When to reach for this - Writing a build prompt, or a session handoff whose final step is a build. - Delegating a contained build/fix you want to run unattended or near-unattended. - Any time you're tempted to write "go build X and let me know" — that's the low-reward path; this skill is the high-reward replacement. ## The anatomy — the parts that make it work 1. **Goal + philosophy in one breath.** The first line states *what* to build AND the guardrails it must respect (e.g. "…remove manual ceremony; the read-only dashboard and live daemons are untouched"). The agent knows the point and the boundaries before it reads anything else, so it never optimizes in a direction you'd reject. 2. **State block — kill the discovery tax.** Name the working tree, the identity ("you are the build user, already in the repo"), and the active constraints ("the commit hooks are installed; commits must stay single-capability, docs-only"). Every fact the agent would otherwise spend tokens *discovering*, you hand it. Unspecified context doesn't make the work go away — it makes the agent pay to rediscover it, in tokens and in wrong guesses. **Fold scope into the build for facts you don't have.** The state block hands the agent every fact you *have*. For facts you *don't* — which hooks are installed, what an output schema actually contains — and can't cheaply get yourself, don't write a separate recon pass: fold the discovery into the build prompt as an investigate-first step that *reports what it found, then proceeds* (behind a gate if the finding could change the plan). One session scopes and builds, and you still get the answer key, because the report is part of the output contract. 3. **Split certain work from uncertain work.** Put the locked, fully-specified work in one part ("BUILD FULLY"). Put the genuinely uncertain work behind a **decision gate** in another ("INVESTIGATE FIRST, then build OR defer"). Never blend them — blending forces the agent to either over-build the uncertain part or under-prove the certain part. The split is what lets one prompt safely contain both a knockout and an unknown. 4. **Behavior as numbered, testable specs.** Enumerate each behavior the artifact must have ("require ≥2 args; allowlist guard; stage only named files; surface a hook block and exit nonzero with no retry"). Each line is independently checkable. "Done" stops being a vibe and becomes a checklist the agent — and you — can run down. 5. **Embedded fire-tests WITH an answer key.** For each test, specify: command → expected observation → expected exit code → pass/fail. *Falsifiable* means *specific*: "exit 1, names the file, nothing staged." The agent doesn't self-grade subjectively; it grades against a key you wrote. This is the single highest-leverage element — it's "verification is the product" compiled into the prompt, and it's the reason you can **trust the green** instead of re-checking by hand (which would erase the savings). 6. **Mandate a restore point + cleanup.** "Capture a restore point; use a scratch file in-repo; reset after so no test commit remains." The prompt owns the mess so the session leaves none. This is why a well-run session ends with a clean tree instead of scratch artifacts you untangle next time. 7. **License the deferral on the uncertain branch.** Spell out: clean criteria → build; gnarly criteria → STOP, report the mapping, defer. Then add the explicit value statement — *"a correct deferral beats a [renderer] that silently [drops half the work]."* This converts "the agent might build the wrong thing" into "the agent makes a bounded, pre-authorized call." It is exactly why a deferral lands as a **clean, complete outcome** rather than a botched half-build. An agent that declines to build the wrong thing is a stronger signal about your harness than one that builds the right thing. 8. **Pre-design the integration / composition test.** If two pieces must work together, specify the end-to-end proof in advance ("the renderer produces the doc on-box; the commit utility commits it through the governor; the two compose"). The agent proves the *seam*, not just the parts — which is where contained builds usually break. 9. **Pin the implementation constraints.** Language, stdlib-only (or name the one unavoidable dependency), which files must never be corrupted, "show `git status` clean at the end." Removes a whole class of implementation dithering and protects the system of record from a careless write. 10. **State the output contract.** Say exactly what the session must return ("final output = the fire-test table AND the binding mapping"). You get a *verifiable artifact* back — a table you can check against the answer key — not a wall of prose you have to mine for whether it actually worked. ## The deeper principle (the transfer) This skill is the **delegation gate stated as a recipe.** A task is safe to hand off when it is *specifiable AND checkable* — and a prompt built this way has **made** the task checkable by carrying its own falsifiable tests. Writing the verification into the prompt is the *engineered-lane move applied to delegation itself*: you don't wait around for a task to become verifiable, you invest the up-front specification that makes it so. > **Verification is the product; the autonomy is the dividend.** The prompt that carries its own answer key is the unit you can promote up the autonomy ladder — because the proof travels *with* the work. You're never trusting the agent's judgment; you're trusting a check the agent can't skip and that you wrote in advance. (In an enterprise setting this is the same move: an agent gets a schema-checked, audited path and a test it must pass — not free rein and your good faith.) ## The decision-gate pattern (worth its own callout) When part of a task is uncertain, do **not** ask the agent to guess, and do **not** leave it open-ended. Give it three things: - the **criteria** that distinguish the easy case from the hard case, - the **full instruction for BOTH branches**, and - an **explicit license — and stated preference — to defer** the hard case cleanly. A decision gate is how you delegate work that *contains* an unknown without delegating the *judgment* about what to do with the unknown. It is the mechanism that lets you put genuinely uncertain work into an otherwise-locked prompt and still trust the result. **The gate is a premise-check, not just a difficulty-sorter.** Its investigation can surface that the *task's own premise* is wrong — not merely that a sub-case is hard. A prompt once told the agent to "centralize the single model-host value"; the agent's investigation found there *is* no single value — two functionally divergent endpoints sharing one host, one taking a message list and the other a flat prompt — and it returned a *re-framed* option (one host, two derived endpoints) rather than forcing the collapse the prompt assumed. So when you write a gate, license the agent to challenge the **framing**, not only to defer a hard branch. The strongest gate outcome isn't "deferred the hard case" — it's **"caught that the task assumed something false and proposed the corrected shape."** That is the answer key catching an error in the question, and it's the highest-value thing a delegated investigation can return. ## Pre-scoping at handoff: tier the batch before anything fires It is tempting, at session close while context is rich, to pre-scope a stack of build prompts so they can be fired later "from the car." This is correct **for CLEAN-path builds and a trap for everything else** — and the difference is the whole discipline. **The rule:** pre-scope a prompt at handoff **iff** the build is *decision-resolved*. A decision-resolved build can carry its own answer key (numbered specs + fire-tests); a **decision-blocked** build cannot — pre-scoping it just freezes a premature guess into an authoritative-looking prompt. The most dangerous batch is N "ready" prompts where several silently encode unmade decisions: that ships a **phantom floor**, the exact failure the fire-tests exist to prevent. **So a batch is a SORT, not a count.** Before writing any prompt, tier every candidate: | Tier | Test: *could the agent self-grade this green without me?* | Form | |------|------------------------------------------------------------|------| | **CLEAN** | Yes — decision-resolved, carries fire-tests | Full prompt; fires unattended | | **GATED** | No — one decision unmade | Prompt with a STOP-AND-ASK gate up top; fires *after* the decision | | **CHAINED** | No — blocked on another build shipping | Drafted, held | | **DESIGN** | Not a build at all (manual / decision session) | A decision card, never a prompt | The discriminator is always the same question: *could the agent self-grade this green without me in the loop?* CLEAN = yes; anything else is not CLEAN, and writing it as fire-and-forget is dishonest about the floor. **Why this is the same idea as everything above, not a new one:** the tier sort IS the delegation gate applied to a *set*. CLEAN = adequate controls → automate. GATED/DESIGN = controls not yet adequate → ceremony (a decision) first. You are not deciding what to fire by *size* or by *how exciting it is* — you are deciding by whether the prompt can carry its own answer key. A decision-blocked row's cheapest control is a 10-minute human decision that *converts it* into a CLEAN prompt; spend that, then fire. **The loop:** decisions earn prompts. Each answered decision promotes a GATED row to CLEAN. Run the batch as: sort → fire the CLEAN tier → take the decisions that unblock the GATED tier → re-sort next cycle. A manifest that doesn't change between sessions means nothing shipped — that's the signal, not the steady state. ### Cross-fire: the sort says what can FIRE, not what can fire TOGETHER The CLEAN/GATED/CHAINED/DESIGN sort tells you which prompts are *ready*. It does **not** tell you which can share one session. A second, independent constraint governs that: **file collision.** Two CLEAN prompts that both write the same file cannot safely share a session — the second commit re-reads a tree the first just changed, and two commits to one file in one session is where a clean batch turns into a tangle. This bites hardest on **hub files** — the handful of god-files that a third of all rows seem to touch. The move: before batching, **map each prompt's write-set.** Rows with disjoint write-sets batch into one session. Rows whose write-sets intersect on a hub file go in **separate sessions** — or, only when deliberate and the edits land in genuinely different regions of the file, as ordered commits within one session, re-read between (the riskier path; default to separate). The discriminator: *does this prompt write a file another queued prompt also writes?* If yes, they don't share a session no matter how CLEAN both are. This is why a batch is **sequenced, not just sorted** — the sort picks the tier, the write-set map picks the order. ## Template (skeleton) ``` GOAL: + . REPO/STATE: · · . ──────────────────────────────── PART 1 — — BUILD FULLY ──────────────────────────────── BEHAVIOR (numbered, each independently testable): 1) ... 2) ... 3) ... BUILD: write it, DISPLAY it before any write, commit as ONE capability. Subject: "". FIRE-TESTS (report a table: test → observed → exit → pass/fail vs expected): capture a restore point; use a scratch target IN the repo; reset after (NO test commit remains; show git log/status restored at the end). 1) → → exit 2) ... ──────────────────────────────── PART 2 — — INVESTIGATE, THEN BUILD OR DEFER ──────────────────────────────── a. . b. REPORT the mapping as a table BEFORE writing any code. c. DECISION GATE: - CLEAN (): build it. Verification = . (Note WHY that verification fits the lane.) - GNARLY (): STOP. Report why it's underdetermined, and defer. A correct deferral beats a forced half-build. d. IF it builds: commit it as its own capability, THEN run the COMPOSITION test proving Part 1 + Part 2 work together end-to-end. CONSTRAINTS: · only named files in any commit · never corrupt · git status clean at end. OUTPUT: . ``` ## Hard rules every prompt inherits (non-negotiable, encode them) These are guardrails, not preferences. A prompt that omits them delegates a way to fail. - **Data-class exception — personal/child data is hold-back-by-default, NEVER commit-and-flag.** When a build touches personal or child data (names, birthdates, household records), the default is to **hold it back**: it never enters tracked code, tests, fixtures, or the system-of-record — synthesize a fixture instead. Do **not** "commit it and flag it for review" — that is backwards, because the flag rides in *after* the data already reached history, where a later delete does not erase it. (This is a real observed miss: personal data was committed-and-flagged instead of held back.) The block-level pre-commit guard is the **backstop for the mistake, not a license to make it** — design the prompt so the guard never has to fire. - **Dispatch pre-check = INDEX grep PLUS a full-text scan of the corpus.** Before authoring a new probe or build prompt, grep the machine-generated index by status/tag — **and then full-text-grep the document corpus itself** for the work's key terms. The index alone is NOT sufficient: its regeneration is a manual step, so it CAN lag the tip, and a spec that landed un-indexed reads as absent. (Observed: a design was blocked at intake as new work while its spec had been on disk the whole time.) If the work is already a design-of-record, **DRAIN it (build), don't re-author.** - **The human-only trailer is HUMAN-only — an agent never self-assigns it.** Where a commit trailer carries the human's difficulty calibration, and a separate field carries a boundary reviewer's verdict, both derive their entire value from HUMAN authorship (a hook makes the trailer physically unforgeable by an agent). A prompt must never instruct an agent to add, predict, or backfill one — when the warning fires for a missing trailer, **let the warning stand.** - **Answer keys carry NO ambient state.** Every fire-test in the answer key must be reproducible from the prompt's own fixtures: never assert on the wall clock, today's date, pre-existing runtime files, or the residue of a prior run. (The precedent: a render that stamped wall-clock time made its own golden drift merely by existing.) If an assertion needs a date, the fixture carries the date; if it needs prior state, the prompt mints that state first. - **`launched != running` — verify the first observable effect, never the launch receipt.** A process that *started* is not a process that is *doing the work*. Confirm the FIRST real effect it produces on its own — a file written, a row landed, a card that actually renders — before you treat a launch as a run. A green "started" line is not progress. - **Never trust a tool's own success message — verify the artifact.** A tool that prints `DEPLOYED` / `DONE` / `OK` is making a *claim*, not furnishing *proof*. Re-read the artifact it says it produced and check it (digest, bytes, on-disk state) against intent. (Observed: a deploy gate printed "DEPLOYED (7 files)" while writing nothing; the fix made a landed-write digest re-verify structurally mandatory.) The prompt-level consequence is a law about fire-tests: **the answer key asserts on the ARTIFACT, never on the tool's self-report.** ## Anti-patterns — the low-reward session - **Vague goal** ("clean up the deploy stuff") → the agent spends its budget guessing your intent, and may guess wrong expensively. - **No state block** → the agent rediscovers the repo, the constraints, the identity — paying the discovery tax in tokens and in actions taken against stale assumptions. - **No answer key** → the agent self-grades on vibes; you can't trust the green, so you re-verify by hand and the delegation saved you nothing. - **No cleanup mandate** → test commits and scratch files pollute the tree; the next session opens on untangling state instead of doing work. - **Uncertain work with no gate** → the agent either stalls asking, or charges ahead and builds the wrong thing. Both are failures; the gate prevents both. - **A pre-scoped batch that isn't tiered** → decision-blocked builds dressed as ready prompts; firing them ships a phantom floor. Sort the batch before any prompt is written. - **No output contract** → you get prose when you wanted a verifiable table. ## Provenance Distilled from a relay on delegating control through code verification: a single handoff carrying one of these prompts produced **two shipped quick wins in ~20 minutes at low token cost** — one tool built and fire-tested green, one cleanly **deferred at its decision gate** when its data-binding turned out to be underdetermined. The deferral landing as a clean, complete outcome — not a half-build — is the decision-gate pattern doing exactly its job, and is the clearest proof that the *verification*, not the build, is what you were really delegating. The batch-tiering section was added after a session-close batch where 8 of 15 candidates were decision-blocked: the sort, not the count, was the deliverable. Cross-fire, gate-as-premise-check, and fold-scope were earned in a later backlog-drain session: a config-centralize prompt's gate caught a false "single value" premise, and three queued prompts collided on the same two hub files and had to be sequenced by write-set, not just sorted by readiness.