jschoubben
3f6d939930
papa-hq has no ledger. Its root is AGENTS.md, CLAUDE.md, README.md, every decision is a numbered record, and its graduation playbook has no path for an unrecorded decision. hal-hq now matches. The ledger's 41 entries classified as: 10 restating a record, 11 restating design docs, 15 describing how this repository works with the reasoning sitting in a README rather than anywhere citable, 3 small rules with no home, 2 superseded stubs. Mostly a copy — and a hand-maintained index, the exact pattern ADR 0022 had just rejected for the decision index on the grounds it drifted after one addition. Keeping one copy of that while removing another is not a position. It also collided by name with 02-DECISIONS/ in any directory listing. Nothing was dropped. Records 0019-0025 give the repository decisions the reasoning they never had: HQ is its own repository and is public, design has two layers, work moves through playbooks, status lives in frontmatter, issues have a front door, the numbering is the flow, HQ is the source of the constitution. 0026 records the ledger's own removal. The three orphan rules went to how-we-build, where a rule is enforced and keeps the incident that earned it — the package rule was genuinely unwritten anywhere. Two lab decisions stated only in the ledger went into the lab design. "Deliberately not decided" went to the research effort and design document each question actually belongs to. The chronological view the ledger provided is now generated from record frontmatter, which is what it was for. The cost, stated in 0026 rather than glossed: a record is more work than a table row, so the risk is a small decision going unrecorded because nobody wanted to write a document. how-we-build takes rules cheaply, which is the mitigation, not a solution.
58 lines
2.5 KiB
Markdown
58 lines
2.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.
|
|
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 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.
|
|
|
|
## 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.
|