# 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, give the issue the document path in the issue tracker:
   `amended-design` on its `issue-tracker.move` to `resolved`, or `issue-tracker.link` with kind
   `design` before then — never in the report's frontmatter
   ([ADR 0275](../../02-DECISIONS/0275-the-mesh-numbers-and-tracks-its-issues-in-a-module-of-its-own-and-hq-keeps-only-the-narrative-of-a-design-or-governance-issue.md)).

## 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.