shape
The second gate. A record leaves it with an intent, mini-requirements and a proof contract a reviewer can check without asking you. It does not build.
The record: in an OpenRig rig, the slice folder. Elsewhere, the bench record the workbench skill resolves (records.cjs resolve).
Modes
| Mode | When | Reads | Writes |
|---|---|---|---|
| default | the record exists, and its requirements or contract are thin or missing | references/sequencing.md when the build takes more than one sitting |
SPEC.md, plus PROGRESS.md ## Plan if sequenced |
--grill |
a plan or idea exists and has to be stress-tested | references/grill.md |
nothing until the answers are in, then SPEC.md |
--options |
the approach is not obvious | references/options.md |
reports/options.md |
Default steps
- Read the record. If
SPEC.mdalready meets steps 2 to 6, change nothing: say it is ready and name the next gate (build, thenvd:code-reviewandvd:verify). - Intent: one or two sentences in plain words: who gets what, and why.
- Mini-requirements: numbered, observable, testable outcomes ("
total()counts a repeated coupon once"), not tasks ("refactor cart"). Each one maps to a contract line, its success check. - Proof contract:
- keep what intake wrote; none there, build the lines from the single source:
node <intake>/scripts/contract.cjs <type>; - make every line concrete: name the test, the surface or the number;
- add the door type (one-way: hard to undo, such as data or a public API; two-way: a revert undoes it), the blast radius and the undo step if missing.
- keep what intake wrote; none there, build the lines from the single source:
- States, only when the frontmatter names the
statechartlens. Withvd:statechart:- for work on existing code, two charts: today, modeled from the code, in
reports/statechart/today/, and intended, from the rules, inreports/statechart/intended/; new work gets the intended chart only; - each rule is a numbered mini-requirement ending
(invariant)and anINVARIANTof the intended model. A rule the ask states is approved; ask the reader before adding any other; - one contract line per invariant and per bug path the today chart marks, each a test that fails on today's code and passes after the change;
- the charts' paths in
SPEC.md, under## States.
- for work on existing code, two charts: today, modeled from the code, in
- Out of scope: one line, so the reviewer knows what not to ask for.
- Frontmatter, when intake left none:
id,type,intent,depends_on(the slices this waits on). - Territories: when the build spans repos, one worktree per repo and one PR by default. Name them here.
- Check: no
TODOis left. The record must passrig scope auditin a rig, or the workbenchcheckelsewhere.
Rules
- Never invent a requirement the ask does not support. If one is needed, ask one question and give your best guess with it.
- One question at a time, in every mode.
- Shape writes the record only. Code, plans in new files and prototypes are out of scope; the statechart model and charts under
reports/statechart/are part of the record.
