# 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 [`adr/`](../../adr/) taking the next free
   number. Format and rules are in [`adr/README.md`](../../adr/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 `02-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: [adr/NNNN-....md]
   ---
   ```

4. **Close the effort.** Set the effort's `status.md` frontmatter to `status: graduated` and
   `became:` pointing at the design document and the decision record.
5. **Add a ledger line.** Append the decision to [`DECISIONS.md`](../../DECISIONS.md) under
   today's heading, pointing at the 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: adr/NNNN-....md` — **its text is never edited**.
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.
4. Add the ledger line.

## When something ships

Implementation state is a third axis, independent of both design and decision.

1. Write or update the matching document under `02-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.