jochen
2349f4bb63
A review found the check too lenient: an issue cited as context beside a deferral passed it, and one insight excused every deferral in a record. The tracking issue is now named as tracking it, an insight covers only its section or what it quotes, and the phrases include "not decided here", "postponed" and "future work". ADR 0273's four undecided items get issue 357.
69 lines
3.5 KiB
Markdown
69 lines
3.5 KiB
Markdown
# 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
|
|
|
|
1. **Check it against GENESIS.** An effort graduates only if its conclusion is traceable to
|
|
[`mission.md`](../mission.md), [`context.md`](../context.md) and
|
|
[`effect.md`](../effect.md). If it conflicts, either the effort is wrong or GENESIS is —
|
|
say which, in writing, before proceeding.
|
|
2. **Record the decision.** Write a record in [`02-DECISIONS/`](../../02-DECISIONS/) taking the next free
|
|
number. Format and rules are in [`02-DECISIONS/README.md`](../../02-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](../../04-ISSUES/354-a-decided-rename-was-never-scheduled-and-the-operator-believed-it-live/00-report.md),
|
|
ADR 0244's code renames). [`cycle.py`](../checks/cycle.py) holds every accepted record dated from
|
|
2026-10-09, and an older one corrected under the rule, to it.
|
|
3. **Write the design.** Create the document under `03-DESIGN/01-to-be/` with frontmatter:
|
|
|
|
```yaml
|
|
---
|
|
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]
|
|
---
|
|
```
|
|
|
|
4. **Close the effort.** Set the effort's `00-overview.md` frontmatter to `status: graduated` and
|
|
`became:` pointing at the design document and the decision record.
|
|
|
|
## Amending an existing design
|
|
|
|
A design changes only through a decision.
|
|
|
|
1. Write the decision record. If it reverses an earlier one, the earlier record's `status:`
|
|
becomes `superseded-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`](../../02-DECISIONS/README.md)).
|
|
2. Edit the to-be design document and set `updated:` to today.
|
|
3. If the amendment came from an issue, set that issue's `amended-design:` to the document
|
|
path.
|
|
|
|
## When something ships
|
|
|
|
Implementation state is a third axis, independent of both design and decision.
|
|
|
|
1. 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.
|
|
2. Set the to-be document's `status: implemented` and its `code:` to the owning repositories
|
|
from [`repos.md`](../repos.md).
|
|
3. `status: implemented` must be defensible from the owning repository's main branch, not from
|
|
intent. If it cannot be checked, it is `in-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.
|