Orchestrata Ultimate / Briefs / Writing a brief

Writing a brief

A worker is a fresh session. It sees the brief and the files under its working directory, nothing else. Every rule below exists because a dispatch failed without it. The failures are recorded in plans/briefs/IMPROVEMENT-LOG.md (defects D1 to D22, 2026-10-22) and in the maintainer's notes on better briefs, and each lesson here names its source.

The rules

#	Rule	Why, measured
1	Put the measured state in the brief and say "do not re-measure". Include tables, numbers and what the tree already holds.	An installer worker with a vague brief measured things the coordinator could have measured, then spent its whole time cap in preflight (2026-10-22).
2	Decide the design before dispatch. Close every "measure, then decide" fork yourself. A fork that appears mid-run is a STOP, not a worker decision.	Builders are not designers; the template tells them to stop and report.
3	Give a VERIFY command that has already run green somewhere. Quote its exact text, its expected wall time, how to wait for it and its log path.	The first installer brief named a runner that cannot finish in 300 s, because a 180 to 234 s trace refresh runs after every source edit.
4	Name the known traps and why earlier runs failed.	Hook-rewritten maps and `plans/ast-*.json`, a mypy step that times out cold at 30 s, and Python read without the toolkit each cost a run.
5	Set a run budget: at most N VERIFY runs, then STOP and report from the log.	Without a cap the worker burns its time re-running.
6	List the exact staging paths and the files never to stage.	The pre-commit hook stages `reports/precommit-walls.ndjson` into every commit by itself (D11, D12); an unlisted file reads as a fence violation.
7	Make the prompt self-contained. Never write "read the brief file" or "the format is in the brief".	A rejected dispatch on 2026-10-22: the worker has only the text it was given.
8	Name the code facts: functions, line ranges and what they return, read with the AST toolkit. Quote exact strings (output formats, warning texts) verbatim.	The worker otherwise guesses at structure; one trap named in the notes is a loader that re-executes its module on every call.
9	Give a proof script the worker runs itself, comparing old and new output on the same tree.	The coordinator re-runs VERIFY and compares; a script makes the comparison mechanical.
10	Do not let an input change between measuring and dispatching. Re-measure after any cleanup.	D14: a blast radius of 568 modules was measured against a regenerated AST snapshot, then the snapshot was restored to its committed version and the worker's run was refused.
11	Say why a rule exists, not only that a hook enforces it.	D13 and D15: a rule held only by a hook is dropped where the hook is silent; the zero hand-reading mandate for Python was broken by both a worker and a coordinator.
12	Never delegate a prod deploy. End the brief before it.	D17: the auto-mode classifier denied a prod promote to a subagent.
13	Estimate from the work list (files times tests times runs), not from one favourable fact.	D20: "+15 to 20 min" turned into about 2 to 2.5 hours.

Labels the hook checks

task_context_hook.py tests, for each of GOAL:, FILES:, CONSTRAINTS:, DONE WHEN: and VERIFY:, whether the string occurs in the upper-cased prompt. A label with any qualifier between the word and its colon does not contain the string, so the dispatch is denied with the five-line skeleton.

Written	Result	Why
`FILES: scripts/foo.py (modify), tests/test_foo.py`	accepted	literal label, contains a `.py` path
`FILES (yours alone; read-only context below):`	rejected	no `FILES:` substring (D16, D19)
`VERIFY (budget: 2 runs):`	rejected	no `VERIFY:` substring
`VERIFY: ./check.sh (budget: 2 runs)`	accepted	put the qualifier after the colon
`FILES: see the list below`	rejected for coding tasks	development and testing tasks must name at least one `.py` path in the `FILES:` field
`DONE WHEN:` missing	rejected	all five labels are required
builder, wirer or refactorer with no `DESIGN_WAIVER:` line	rejected by the design hook	RUL-022, ADR-0048; the line must start with `DESIGN_WAIVER:`, not sit inside the GOAL sentence

Two details from the hook source: the FILES: field is sliced out of the prompt up to the next required label, and only paths inside that slice are used for the attached AST, so a .py named only in prose earlier in the brief does not count when FILES: itself names none. The check is a substring test, not a line-start test, but the template asks for line-start labels, and D19 shows that copying the label line from the skeleton verbatim is the safe habit. The maintainer's notes record the hook bouncing a dispatch three times on 2026-10-22 over variants such as VERIFY (budget...):.

A skeleton that passes

DESIGN_WAIVER: ADR-NNNN settles the design (<date>); no fork remains.
GOAL: make gen_codebase_map.py --with-full re-parse only changed files; a no-change run takes 3 s or less (was 11.7 to 13.9 s) and both maps stay byte-identical.

MEASURED (do not re-measure): cProfile of one run on this tree: <table>.

FILES: scripts/gen_codebase_map.py (modify). Never stage plans/ast-*.json or docs/CODEBASE_MAP*.md.
CONSTRAINTS: no commit, no git add; read Python through the AST toolkit only; no new dependencies.
DONE WHEN: 1. two consecutive runs with no edits take 3 s or less each. 2. the map files are byte-identical to the previous run's.
VERIFY: <command that already ran green> (expect about N s; log at <path>; at most 2 runs, then STOP and report from the log).

The shape of the first lines follows a real brief, 2026-10-22-maps-delta-builder, whose GOAL, FILES and Measured state (do not re-measure) sections carry the measured profile. The skeleton above is shortened and its DESIGN_WAIVER text is illustrative; use the full templates for real dispatches.

Known traps, in one list

A foreground command that merely names a test runner is refused as an unobserved test run; name the log file instead (D9).
The secrets scanner refuses credential-shaped names in staged files, fixtures included; rename, never bypass (D2, D10). Run the scanner on the staged files before dispatch.
The commit review's mypy step times out at 30 s on a cold cache; warm it first (D3).
Pre-existing environment-variable literals in a touched test file are flagged (D4).
A full-suite brief starts with a fleet pre-flight, because stopped fleets fail modules for unrelated reasons (D7).
For any deploy, read the dry run in full and diff the lock between the deployed and the new commit; a removed package that runtime code imports is a STOP (D18).

The loop