Orders: how work is specified · Saphan Studio documentation

An order is the written specification a stream runs against — the contract between the person who wants the work and the agents who will do it. Orders are documents in your project's command deck, and the discipline around them is where most of the method lives. A complete order carries:

Section	What it settles
Class and observation	What kind of work this is, and the concrete observation that motivated it — a measured defect, a named requirement. Not "improve X"; what happened.
Confinement	What this stream does not touch. Named explicitly, so scope creep is visible as a violation rather than discovered afterwards as a surprise.
Scope	The work itself, broken into named pieces, each with its rationale — and, where a choice between variants exists, the chosen variant stated as a decision.
Owner questions	Decisions the order cannot make alone, named and put to the human before implementation — never resolved silently by the executor.
Collisions	The streams this one could interfere with, and the ordering decision.
Test plan, RED first	For each guarded behaviour: a test that proves it, and the negative control — the mutation that must turn the test red. A test that cannot detect the failure it guards is listed as a defect of the plan.
Definition of Done	Checkable conditions. If the order chose a variant, the DoD includes an assertion that turns red if the rejected variant is delivered — a design decision must be testable, or it is a comment.
Budget	Model tier, quote, and cap — per run, visible before dispatch. Overruns are named events against the quote, not ambient noise.
Assumptions of intent	What the order believes about the world, stated so that a false assumption can be recognized and the order revised — rather than the executor improvising around it.

A compact skeleton. The first lines are read by machine: the heading must be exactly # ORDER — <stream-slug> with nothing after the slug, and the - key: value bullets directly under it carry what saphan dispatch place reads — repository, base, branch, quote (or cap) and wall-clock limit. Everything below them is for the people and agents doing the work. saphan dispatch template executor prints your workspace's own template, which is the better starting point when one exists.

# ORDER — <stream-slug>

- repo: <the repository's name in the workspace, or its absolute path>
- base: <the branch or commit the stream is cut from>
- branch: <the stream's own branch>
- quote-usd: <n>
- cap-usd: <2x the quote>
- wall: <wall-clock limit in minutes, e.g. 90m>
- reason: <why this order exists now>

**Class:** <defect | feature | recon | hardening>
**Observation:** <the measured thing that motivated this — dated, concrete>

## Confinement — what this stream does NOT touch
- <boundary 1>
- <boundary 2>

## Scope
### P1 — <named piece>
<what and why; chosen variant stated as a decision>

## Questions to the owner — required before implementation
**Q1 —** <the decision the order cannot make alone>

## Collisions
- <stream X touches the same surface — this leg goes second>

## Test plan — RED first
| id | proves | negative control |
|---|---|---|
| T1 | <behaviour> | <the mutation that must turn T1 red> |

## Definition of Done
1. T1–Tn green, full tree green.
2. <the variant assertion — red if the rejected variant ships>

## Budget
- model tier: <tier> — the quote and cap are the bullets at the top (per run)

## SKILLS
- <a skill from your workspace's skill library, if the leg needs one>

## Assumptions of intent
1. <assumption — if false, which part of the order falls>

Once the order is written, committed and approved by a person (saphan order sign <path>), saphan dispatch place --order <path> --role executor starts it on a free seat in one step; Placing a leg walks through it.

Recon before repair is a standing habit: when the root cause is not known, the order buys a diagnosis with evidence first — read-only, cheap, gated by the human — and the targeted fix is a separate order afterwards. Ordering the fix before the diagnosis is called what it is — buying a lottery ticket.