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