jschoubben
c0b35652d0
papa-hq reads 01 research -> 03 decision -> 02 design. The order is a scar, not a choice: 02-DESIGN existed from its initial commit, and when adr/ was finally promoted on 2026-07-13 it took the next free number rather than its place in the sequence. By then design was too settled to renumber. hal-hq was three commits old, so it is not. adr/ becomes 02-DECISIONS and 02-DESIGN becomes 03-DESIGN, and following the folder numbers now walks the process in the order it happens: research produces a decision, the decision authorises a design. 00-GENESIS becomes 00-META, matching papa's rename from the same restructure. Every path reference rewritten across documents, frontmatter, playbooks and skills. All links resolve; all 58 frontmatter blocks parse and their path fields still point at files that exist.
47 lines
2.1 KiB
Markdown
47 lines
2.1 KiB
Markdown
---
|
|
name: hal-amend-design
|
|
description: Use when a hal-hq design document must change, or when an as-is document is found to be wrong about what the mesh actually does. Triggers on "the design changed", "that's not how it works any more", "update the as-is", "this shipped differently".
|
|
---
|
|
|
|
# hal-amend-design
|
|
|
|
Changes a design document. **Authoritative playbook:**
|
|
[`00-META/process/02-graduation.md`](../../../00-META/process/02-graduation.md).
|
|
|
|
## Which layer is being changed
|
|
|
|
**Establish this first — the two amend for opposite reasons.**
|
|
|
|
| Layer | Amend when | Requires |
|
|
|---|---|---|
|
|
| `01-to-be/` | The intention changed | A decision record. Always. |
|
|
| `00-as-is/` | The mesh changed, or the document was wrong about it | Evidence from the implementation. Never a decision. |
|
|
|
|
An as-is document is corrected against **what the code does**, not against what anyone meant.
|
|
If the implementation and the intention disagree, the as-is document records the implementation
|
|
and says they disagree.
|
|
|
|
## Amending the to-be layer
|
|
|
|
1. Write the decision record. If it reverses an earlier one, that record gets
|
|
`status: superseded` and `superseded-by:` — its text is never edited.
|
|
2. Edit the design; set `updated:` to today.
|
|
3. If this came from an issue, set that issue's `amended-design:`.
|
|
4. Add the ledger line to `DECISIONS.md`.
|
|
|
|
## Amending the as-is layer
|
|
|
|
1. Establish what is actually true — from the code, a pipeline log, a live query, the
|
|
operational record. Not from a design document.
|
|
2. Edit the document. Set `updated:` only if the **implementation state** changed; a
|
|
correction to text that was always wrong does not change it.
|
|
3. If the correction reveals that something shipped differently from its design, say so in the
|
|
as-is document and leave the to-be document alone. That divergence is a finding, and may
|
|
deserve an issue.
|
|
|
|
## Do not
|
|
|
|
- Do not put a future intention in an as-is document.
|
|
- Do not quietly fix a wrong claim that held up a decision. Record that it was wrong and where
|
|
it was relied on — that is the failure this repository exists to name.
|