---
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-GENESIS/process/02-graduation.md`](../../../00-GENESIS/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.