jochen
daa9f171ae
The import of slice 3 (ADR 0275) was checked against every folder: no report changed since the commit it read, and the tracker holds each report's status, owner, fix, design amendment, replay and closing day. The keys are removed from all 361 reports, cycle.py refuses them in any report, and the playbooks, skills and READMEs that still pointed at them name the tracker instead.
3.8 KiB
Playbook 02 — Graduation and design change
Trigger. A research effort concludes, or an existing design must change.
Who runs it. Anyone, with the decision recorded before the design moves.
Graduating research
-
Check it against GENESIS. An effort graduates only if its conclusion is traceable to
mission.md,context.mdandeffect.md. If it conflicts, either the effort is wrong or GENESIS is — say which, in writing, before proceeding. -
Record the decision. Write a record in
02-DECISIONS/taking the next free number. Format and rules are in02-DECISIONS/README.md. State evidence, not assertion, and record the options that were rejected — that is the half worth keeping. A record that puts work off — a rename, a check, a case it does not handle — names the issue that tracks it and the owner who will do it, in the sentence that defers it ("tracked by issue N"), or the deferral is not accepted: a deferral nothing tracks reads as done (issue 354, ADR 0244's code renames).cycle.pyholds every accepted record dated from 2026-10-09, and an older one corrected under the rule, to it. -
Write the design. Create the document under
03-DESIGN/01-to-be/with frontmatter:--- layer: to-be status: designed code: [] # owning code repo(s); set at build handoff, empty before updated: YYYY-MM-DD decisions: [02-DECISIONS/NNNN-....md] --- -
Close the effort. Set the effort's
00-overview.mdfrontmatter tostatus: graduatedandbecame:pointing at the design document and the decision record.
Amending an existing design
A design changes only through a decision.
- Write the decision record. If it reverses an earlier one, the earlier record's
status:becomessuperseded-by: 02-DECISIONS/NNNN-....md— its reasoning is never rewritten. If the earlier record is sound and only a fact in it went stale, that is a progressive insight, corrected in place and marked in the record rather than superseded (02-DECISIONS/README.md). - Edit the to-be design document and set
updated:to today. - If the amendment came from an issue, give the issue the document path in the issue tracker:
amended-designon itsissue-tracker.movetoresolved, orissue-tracker.linkwith kinddesignbefore then — never in the report's frontmatter (ADR 0275).
When something ships
Implementation state is a third axis, independent of both design and decision.
- Write or update the matching document under
03-DESIGN/00-as-is/so it describes what now runs — including anything that shipped differently from the intent. A design that shipped bent is an as-is fact, not a design amendment. - Set the to-be document's
status: implementedand itscode:to the owning repositories fromrepos.md. status: implementedmust be defensible from the owning repository's main branch, not from intent. If it cannot be checked, it isin-progress.
Do not
- Do not move a to-be document into
00-as-is/. Write the as-is document; both stand. - Do not edit an as-is document to describe an intention. That is what the to-be layer is for.
- Do not change a decision record's meaning. Supersede it. Correcting a fact it got wrong, while the decision stands, is a progressive insight — marked and dated in the record, never silent.