What is a recipe

A recipe teaches an agent in a repository it has never seen how to arrive at a capability you already built — the principles it rests on, the ground it needs underneath, the road that looks obvious and dead-ends, the scars, and the price.

It is written for the machine that will implement it. Exactly one section, at the end, is written for you.

Name roles, never instances.

The hardest constraint in the genre isn't length or tone. It's this: the moment a recipe names your files, your commands, or your product, it stops being reproducible anywhere else and quietly turns into a manual for the one project that already has the thing. "The facts file," "the collector," "the optional target the project implements" — never a path, a filename, or a product name.

The test is mechanical: could an agent follow this sentence in a repository that has never heard of yours? If the sentence needs a coordinate to make sense, the sentence is about your repo, not about the capability.

A fixed shape, checked by a gate, in this order.

Frontmatter carries identity, version and provenance. The body then opens with a short narrative summary before the eleven section-by-section gates below.

1. SSummary — a 2–4 sentence orientation: what gets built, why the design transfers, and what result to expect. It stays open on the recipe page and is neutrality-scanned like every other body line.
2. 02The problem — what you don't have, what the output actually is, and how you'll know you have it. Acceptance criteria live here, at the top — not buried at the end where a vague success condition becomes obvious only after the build is expensive to redo.
3. 03Why the obvious approach fails — the fork in the road, named honestly. Without it, the reader just follows their first instinct into the same dead end you already found.
4. 04The principles — the payload. The load-bearing, portable claims that survive on a stack nobody's tested them on yet. Everything below is an instance of something here.
5. 05The ground it needs — the preconditions, stated as a ladder, never as facts (below).
6. 06The contracts — the shapes this capability consumes and emits, shown in fenced blocks, not described in prose. A real implementer once scored a recipe 3/10 on this exact axis: it taught him what to build and handed him nothing to build against.
7. 07The build sequence — one heading per step, and every step ends with a literal **Done when:** line. A sequence without per-step acceptance is a wish list.
8. 08The seams — what must stay configurable, and why: the paths, thresholds and vocabulary that belong to the reader's project, not yours.
9. 09The scars — the highest-value section, the one a clean-room reimplementation cannot produce. Each carries three literal markers: Symptom, Root cause, Fix — fixed so it can't decay into vague regret, and each one earned.
10. 10Verification — the gates that ship with the capability, plus the one live check that says it actually works. Not a promise. A test.
11. 11The trade-offs — what the design costs, what it refuses, and when not to build it at all. A recipe that only advocates is marketing wearing a build sequence.
12. 12For the human — what gets built in plain language, which stack choices are essential or incidental, and what that stack bought and cost.

The eleventh gated section, For the human, closes the authored body with the original stack's essential and incidental choices. An optional appendix is the only place concrete names and paths are allowed; everything above it must stand without it.

A ladder, not a statement.

Most readers will not have what a precondition asks for. That's not an edge case — it's the entire premise of the genre. State a precondition as a bare fact ("you need a machine-readable work-item state") and you've left the reader exactly one honest option: stop. They won't stop. They'll point the capability at whatever weaker thing is lying around, and it will produce confident output over rot.

So every precondition is written as three rungs, and there is no fourth:

Every recipe ends with the same two sections, appended at export time, never authored per-recipe: Adopt it here (probe your repo, map roles onto your own conventions, never silently substitute a weaker source, state the plan before building) and Report back (what you built on, what you degraded, the new scars you hit, anything the recipe got wrong). They're identical across the corpus on purpose — one improvement to the protocol reaches every recipe at once, and no author maintains a private copy that drifts from everyone else's.

This is also the mechanism that makes recipes get better over time instead of going stale the way documentation usually does. A report-back is a new scar. A new scar bumps the version. The recipe a stranger reads next month has already absorbed a failure you hit this month.

The exported file — never the source. The export strips the authoring banner and appends the adoption protocol, so what a stranger receives is complete: the machine payload first, the human closing section last, and instructions for how to get it into a repository that has never heard of yours.

A conformance verdict names a moving constitution.