---
name: hal-graduate
description: Use when a hal-hq research effort concludes and becomes design, or when a design must change. Triggers on "graduate this research", "this is decided", "write the ADR", "close the effort", "the design changed".
---

# hal-graduate

Closes a research effort into a decision and a design, or amends an existing design.
**Authoritative playbook:**
[`00-GENESIS/process/02-graduation.md`](../../../00-GENESIS/process/02-graduation.md) — read
it; this skill adds only the scaffolding.

## Steps

1. **Check against GENESIS** — `mission.md`, `context.md`, `effect.md`. If the conclusion
   conflicts, say which is wrong, in writing, before proceeding.
2. **Write the decision record** in `adr/`, next free number, frontmatter per
   [`adr/README.md`](../../../adr/README.md). `reconstructed: false` — this one is being taken,
   not recovered. Record the rejected options.
3. **Write the design** under `02-DESIGN/01-to-be/` with `layer: to-be`, `status: designed`,
   empty `code:`, today's `updated:`, and `decisions:` pointing at the record.
4. **Close the effort** — the research `status.md` gets `status: graduated` and `became:`
   pointing at both.
5. **Add the ledger line** to `DECISIONS.md` under today's heading.

## Amending an existing design

A design changes only through a decision. Write the record first; if it reverses an earlier
one, set that record's `status: superseded` and `superseded-by:` — **never edit its text**.
Then edit the design and set `updated:`.

## When something ships

Write or update the matching `02-DESIGN/00-as-is/` document so it describes what now runs,
including anything that shipped differently from the intent. Set the to-be document's
`status: implemented` and its `code:`. **The to-be document does not move** — both stand.

`status: implemented` must be defensible from the owning repository's main branch. If it
cannot be checked, it is `in-progress`.

## Do not

- Do not move a to-be document into `00-as-is/`.
- Do not edit an as-is document to describe an intention.
- Do not change a decision record's meaning. Supersede it.