jschoubben
93a1231e00
Skills take the hq- prefix: they are HQ process workflows, not mesh workflows, and HQ is company-scoped now. hq-new-research, hq-graduate, hq-new-issue, hq-diagnose, hq-amend-design, hq-handoff, hq-sync-constitution, hq-status. Forward-looking prose becomes Novox Mesh or simply the mesh — the root README, AGENTS.md, the 00-META README, the mission's module example, and one to-be document that addressed 'someone working on HAL'. Three categories deliberately keep HAL, per ADR 0027: The monorepo is still called hal on the forge. repos.md, every code: field and every located-in: field name a repository that exists under that name, and renaming them in prose would make them false. The as-is layer and the research that measured it describe the system that runs, and that system is called HAL. 124 modules, 9 daemons, a dead containerised node — those are observations, not intentions. Records 0001-0026 are immutable. A record says what was decided when it was decided, and no record is edited for a name. Also repoints ADR 0022's link at the renamed skill — a path fix, which the immutability rule permits, not a change of meaning.
46 lines
2.0 KiB
Markdown
46 lines
2.0 KiB
Markdown
---
|
|
name: hq-amend-design
|
|
description: Use when an 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".
|
|
---
|
|
|
|
# hq-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:`.
|
|
|
|
## 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.
|