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.
2.1 KiB
2.1 KiB
name, description
| name | description |
|---|---|
| hal-amend-design | 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.
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
- Write the decision record. If it reverses an earlier one, that record gets
status: supersededandsuperseded-by:— its text is never edited. - Edit the design; set
updated:to today. - If this came from an issue, set that issue's
amended-design:. - Add the ledger line to
DECISIONS.md.
Amending the as-is layer
- Establish what is actually true — from the code, a pipeline log, a live query, the operational record. Not from a design document.
- Edit the document. Set
updated:only if the implementation state changed; a correction to text that was always wrong does not change it. - 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.