The Recipe Standard

Version: 1.0 · 2026-09-18 What this answers: what a recipe is, what its file has to carry, and what a reviewer will hold it to. Everything here is checkable, and most of it is checked by a script you can run yourself. Who this is for: somebody outside this house who wants to write a recipe, place one, or publish one. It assumes you have never seen our code and never will.

A recipe is a method somebody has written down properly, so that an agent can run it and a person can run it and both produce the same work. This document is the shape that makes those two the same thing rather than two documents that drift.

Every rule below is followed by the reason it exists. A rule with no reason beside it is a convention, and conventions get argued with. A rule whose reason names the failure it prevents can be agreed with, disagreed with, or measured, which is the only way a standard survives contact with somebody who did not write it.

You can check your own file before anybody reads it. The rules in section 12 are implemented in lib/recipe-validate.ts and run two ways: paste your file at /recipes/validate, or run bun run check:recipe over a directory. The validator refuses and never repairs: it will tell you what is wrong and it will not rewrite your recipe.

1. What a recipe is

A recipe is one job: what goes in, what comes out, how you know it worked, and where it stops and asks a person. Not a workflow, not a prompt, not a policy. One job, with a unit arriving and a different unit leaving.

One drawing, two renderings. The method is written once. It is read twice: by an agent, which needs the instruction in full, and by a person, which needs the tool, the time and the end state. Those are not two artifacts. They are one method rendered for two runners, and the whole point of the format is that neither can drift from the other, because there is only one of them.

Why one file and not two. A method kept in two files is a method that disagrees with itself within a quarter, and the disagreement is invisible because both copies look finished. Everything that is true of the work lives in the file below; everything that is true only of one runner is a field on a step.

What a recipe is not.

• Not a workflow. A workflow is several jobs joined. A recipe is one, and the joining is the canvas's job. A recipe that does three jobs cannot be placed in one seat, scored against one bar, or refused for one reason.
• Not a prompt. A prompt is instruction. A recipe is instruction plus the checklist that says whether the output may be returned at all, which is the part a prompt has no place to put.
• Not a policy. A policy says what must not happen. A recipe says what happens, and carries its refusals as locked checklist lines, which are enforceable rather than hoped for.

2. The file

One file, SKILL.md, in a folder named for the recipe. Front matter at the top between two --- fences, then the body. The front matter is read by machines and the body is read by whoever runs it.

2.1 The front matter, field by field

One example each, in the order above:

---
name: discount-control
description: Reads a month of quotes and returns one reading per seller. Use when somebody
  asks who is discounting and how much.
license: Proprietary. See LICENSE.txt
metadata:
  author: Archetric
  version: "1.0"
  recipe-origin: house
  recipe-author: Archetric
  recipe-reviewed: ""
  recipe-evidence: ""
  recipe-yields: One reading per seller per month, with an eighteen-line checklist scored
  recipe-gate: Monitors and publishes. Never sets a ceiling and never approves a discount
  recipe-method-id: "convert-discount-control"
  recipe-input-label: Every quote sent this month with its list price and its final price
recipe-verdict-pass: DEFENSIBLE
recipe-verdict-partly: PARTLY
recipe-verdict-fail: NOT DEFENSIBLE
---

Why recipe-method-id and not the label. A recipe joins to the method it implements by id, never by name, because a label is a name and names get renamed. A join on the label survives until somebody improves the wording, at which point the recipe silently belongs to nothing.

Why recipe-reviewed and recipe-evidence are required and may be empty. A missing key and an empty one are different claims. Empty says this recipe has not been reviewed, or has not yet run in a real business. Missing says nobody has considered the question. A recipe acts, so an unreviewed one is not the same risk as an unreviewed article, and the field that says so has to be present for its emptiness to mean anything.

Why recipe-evidence is the field worth more than the method. Anybody can copy a method. What a copied recipe cannot carry is what it has actually returned, in whose business, over how long.

2.2 The body

Eight headings, in this order. Others are welcome between them.

Why the order is fixed and the set is not. A reader who has read one recipe knows where the next one keeps its Report. That is the whole benefit, and it survives extra sections perfectly well: a recipe with a section on its own waterfall is a better recipe for having it. What it does not survive is Edge cases appearing before Where this stops in one recipe and after it in the next.

3. The twelve step kinds

A method is a numbered list. Each step names its kind in parentheses, after the step's own sentence. A step that does two things names both: (Score, then Branch).

Why twelve and why no thirteenth. These are the kinds that survived reading every numbered step of the written recipes. A kind that exists because one recipe wanted it is a kind every other author has to learn and never uses, and a rail nobody can hold in their head is a rail people stop reading. If your step does not fit one of the twelve, it is usually two steps.

Why Look up and Research are separate. A look up fetches a known thing from a known place. A research starts from a question and comes back with a finding and its sources. They reach through the same wall and they are not the same reach, and a method that calls both a look up cannot say which of its steps has an answer and which has an opinion with citations.

Why no Wait and no Loop. A hold is a field on a step, not a card, and a loop is a wire back to a step already run. A card with no work in it is a card nobody can say what takes or yields.

3.1 What a step may carry

Steps a person holds carry three more. How (the tool and where in it), How long (a short phrase), and Done when (the observable end state). An agent needs none of the three, which is exactly why they are required only here: a person asked to do something with no end state written down will either stop too early or not stop at all.

An Act step names its connection and its action. It is the one kind with an effect nobody can undo from inside the canvas, and a step that says "send it" without saying what it sends through is a step whose blast radius nobody can read off the card. An Act step is gated by default, and a business that has decided otherwise says so on the placement, where the decision was actually made, never on the card, where the author would be deciding it for every business that ever places it.

4. Settings

A setting is what a person may turn before a run. Each declares its id, its label, its kind, its default, and what it feeds.

recipe-settings:
  - id: minimum-quotes
    label: The fewest quotes a seller needs before they get a rate at all
    kind: number
    default: 5
    min: 2
    max: 30
    feeds: Which sellers get a rate, and checklist line 6

Why feeds is required. A setting whose effect is not stated is a preference. A setting that says it feeds the returns count tells whoever is reading that the number is a contract, and a run that ignores it has broken something rather than exercised discretion.

Why a value outside the range is refused rather than clamped. Clamping runs the recipe on settings the person did not choose and then reports the result as theirs.

Why an unknown setting id is dropped rather than refused. A browser open since before the recipe was rewritten should run on today's settings, not fail. The asymmetry is deliberate: a stale key is nobody's decision, and an out of range value is somebody's.

A setting with one value is a real setting. Where a recipe has taken a decision out of the reader's hands, the setting appears anyway, with its single value, so that the reader can see which decisions were taken from them rather than discovering it in the output.

Give the recipe a revision limit. A number setting whose feeds names the revision limit is how many rewrite and rescore passes a run gets before it reports the failure instead of rewriting again. Two is the house default.

5. The checklist

The checklist is what a run is scored against, line by line. It lives in the front matter as data and in ## What good looks like as prose, and the two carry the same numbers.

recipe-checklist:
  - id: line-12-no-causal-claim
    line: 12
    question: "Does the reading refuse to claim that any discount won any deal?"
    must: true
    locked: true
    why: the causal claim is the sentence everybody in the room wants, no quantity of quotes
      contains the counterfactual it rests on, and a monitor that supplies it has justified
      discounting using its own output as the evidence

5.1 Mandatory, flexible, locked

The order is run, then placement, then house, and locked is applied last and unconditionally.

Why the layers, in that order. A person should be able to try something once without changing what their business runs on tomorrow.

Why locked is applied last rather than trusted to the layers above. A record written by hand, restored from a backup, or edited in a console is not a validated input, and the line that stops an invented guarantee should not depend on how the record got here.

Why a locked line needs a why. The lock will be argued with, by somebody who has a deadline and a reason. A lock whose reason nobody can read is a lock people route around.

What to lock. Lock a line where breaking it produces a sentence the business will then rely on: a claim the business cannot substantiate, a number measured against a denominator nobody was asked to pay, a causal claim no quantity of the available data contains. Do not lock a line because it matters. Lock it because relaxing it is a decision nobody should be able to make quietly.

Never report a run as passing with fourteen of eighteen. A failed mandatory line is not one problem among several. It is an output whose arithmetic is over the wrong set, or whose most consequential sentence is unsupported, and the count of the lines that passed beside it is a distraction.

6. The gate

Every recipe names the point where it stops and asks a person. It is stated twice on purpose: once in the front matter as recipe-gate, in one sentence, and once in ## Where this stops, spelled out.

Write the gate as what it will not do, not as what it needs. "Drafts only. A person sends every email" is a gate. "Requires approval" is a category.

Why the gate is stated rather than enforced, and why that is said out loud. A recipe is a written instruction to whatever agent runs it. A recipe pasted into an agent that holds send and payment tools is not prevented from using them. The honest claim, and the only one worth making, is that every recipe NAMES where it stops, on the front of the card and not in the small print. Claiming the enforcement would be the kind of promise this format exists to argue against.

A recipe that names no gate is a recipe claiming it never needs one. That is a real answer for a recipe that reads and reports and touches nothing, and it is written down as that answer rather than left blank.

7. The report

The report is the shape of what one run returns. Write it as a fenced block with the fields named and the values shown as placeholders, so an author reading it knows what will be on the page before anything runs.

Four things every report carries:

1. What it read, and when. The window, the system, and the moment it was read. A report with no moment on it is a claim about now that was true at some point, and every figure under it inherits that.
2. What came off the pile first, with the reason. Anything excluded before the work began, listed. An exclusion that happens silently is indistinguishable from something the recipe missed.
3. The roll call. See below.
4. The verdict, with the word first. One word, said once, at the front of the line, then the mandatory lines that decided it. Never a paragraph with the word at the end, and never a fraction.

7.1 The roll call

Every checklist line appears in the report exactly once, by number, with one state and one sentence of reason. Three states and there is no fourth:

CHECKLIST   (one entry per line, line1 to lineN, each scored exactly once)
  line1   <passed | named | failed> · <one sentence>
  line2   <passed | named | failed> · <one sentence>          (mandatory, locked)
  ...
  (every line appears once and exactly once. a line nobody scored is not a line that passed.
   a `named` reason names the missing fact. a `failed` reason quotes the sentence that breaks it)

Why every line, including the ones that came back clean. A compliance block that only appears when something is wrong teaches a reader that its absence means nothing was checked.

Why a line nobody scored is not a line that passed. An unscored output and an output that scored clean are different facts, and folding them together is how a run comes back positive for the wrong reason. A report carrying no self score at all has not passed anything.

Why a failed reason quotes. A reason in the scorer's own words is an opinion about the output. The sentence, quoted, is checkable by somebody who was not there.

Close with what the run would ask. A thin set of ingredients produces a thin output, and the questions that would have thickened it are worth more than another figure.

8. What good looks like, edge cases, and how you know it worked

Three sections, and each answers a question the other two cannot.

## What good looks like is the checklist in prose, numbered to match the front matter, with the mandatory and locked lines marked. It exists because a person reading the recipe to decide whether to place it will not read a YAML block, and the lines are the recipe's actual argument.

## Edge cases is the list of situations that break a naive reading, each with the answer. Write the ones you have actually seen. The test of an edge case is that somebody could reach it on a real Tuesday: "nothing arrived this month" is an edge case, and the reading that says so, reports the count it did read, and does not go looking for something to flag is the recipe working.

## How you know it worked is what is observably different some weeks later, stated so that it could turn out false. Not a time saved, unless something measured it. And the honest failure mode, stated so it can be watched for. A recipe that names the way it will be misused, and the leading indicator of that misuse, is a recipe somebody can keep running safely; one that names only its successes will be trusted past the point where it is still working.

9. The research document

Optional for a listing. Required for house review.

A recipe with no research document behind it is a guess written confidently. The research document is the source of record, the recipe is derived from it, and the two carry the same version number.

Four rules, each with its reason:

1. Name every source, with a URL. A principle whose source cannot be opened is a principle nobody can check, and the first person to check it will be somebody arguing with the output.
2. Distill, never copy. The recipe is your method, written from what you read. Reproducing somebody's text is both a legal question and a quality one: a copied passage carries the source's assumptions along with its words, and you will not notice which.
3. Quotations stay under fifteen words, in quotation marks, with the source named. Long enough to show what was said, short enough that the document is yours.
4. Mark the disagreements. Where two sources contradict each other, say so, say which one the recipe follows, and say why. Say once, in the opening, which kind of source wins where they conflict. A document that resolves a disagreement silently has made the most interesting decision in it invisible.

10. The graded run

Before a recipe is published in the house, it is run on real ingredients and the output is scored against its own checklist, by something other than the thing that wrote it.

Proven versus argued is the sentence that matters. A graded run walks one branch. Every other branch of the recipe is argued, not proven, and the record says which is which by name. A recipe proven on the branch where no ceiling exists has not been proven on the branch where one does, and saying so is worth more than a second run on the same fixture.

Move the arithmetic out of the recipe. Counts, totals, rates and weighted means are where a model's judgment is right and its bookkeeping is wrong. Hand the figures in, computed, and have the recipe say plainly that it uses them as given and does not re-add them.

The verdict word is derived from the roll call, never written first. A report that says the good word while its own self score admits a mandatory line failed is exactly the run this rule exists to stop.

11. The writing rules

12. What the validator checks

Fifteen rules. An error is a recipe the product cannot run correctly. A warning is a recipe that will run and that a reviewer should look at anyway.

Why step-kind is an error one way and a warning the other. A recipe that names no kind at all is a recipe a reader can still follow, whose method the canvas simply does not draw. A recipe that names a kind on eleven steps and not on the twelfth is a different fact: somebody drew the method and left a card the board cannot place.

Why act-step and long-quote are warnings and not errors. Both are judgments about a recipe that will run correctly either way, and a rule that fires on recipes written to this standard is a rule measuring the wrong thing. Where a warning is calibrated against real recipes and still fires on them, the honest move is to leave it visible as a warning rather than delete it.

What the validator cannot check. Whether the method is any good, whether the sources say what you say they say, whether the gate is in the right place, and whether the recipe does one job or three. Those are what review is for, and no amount of format checking substitutes for them.

13. The license line

Every recipe states its license. Two answers are expected:

• Proprietary, pointing at a license file beside it, which is what the house recipes carry.
• The author's own license, named so that a reader can look it up.

The author warrants that the method is distilled, not copied. Naming a practitioner as a source is right and is encouraged: the failure modes in a good method are usually somebody's, and citing them is honest. Reproducing their text is not the same act, and a recipe that does it puts every business that places it in the same position as the author.

Why the line is required even when the answer is obvious. A recipe travels. It gets placed, exported, pasted into somebody else's agent and forwarded to a third party, and at every one of those steps the only thing that says what may be done with it is the line inside the file.

14. Versions

Why a placement keeps its version. A recipe that upgrades under a business silently changes what that business is doing, in a way that shows up first as an output nobody recognizes. The new version is offered, and taking it is a decision with a date on it.

Bump the minor number for anything that changes the output. A new checklist line, a changed default, a step added or removed. A typo fixed in prose is not a version.

Write the version notes for the next author, not for the changelog. The useful sentences are the ones that say which decisions in this version were choices rather than inheritances, and what a reader should look at first if they disagree with the result.