The numbering is the flow: decisions are 02, design is 03

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.
2026-08-23 18:05:11 +02:00
parent f05e4a0dce
commit c0b35652d0
72 changed files with 217 additions and 204 deletions
@@ -0,0 +1,47 @@
+# Playbook 03 — Issues
+
+**Trigger.** Something is wrong at the level of the mesh's design or governance — a rule that
+turns out to be unenforced, a stated behaviour that does not happen, a silent failure the
+design permits.
+
+**Who runs it.** Anyone may open an issue. No localisation is required to report one.
+
+## What belongs here, and what does not
+
+| Belongs in `04-ISSUES` | Belongs in the knowledge base |
+|---|---|
+| The design permits a failure to be silent | How to fix one occurrence of it |
+| A documented rule is enforced by nothing | A command that works around it |
+| A stated invariant is false in practice | A node-specific quirk |
+| The owning component is unknown and finding it needs the whole mesh in view | Symptom → fix, once the answer is known |
+
+The knowledge base already holds the operational record and is indexed on symptoms. This
+folder is not a second copy of it. An issue here is a question HQ must **answer**, not an
+incident someone must **clear**.
+
+## Steps
+
+1. Take the next free number. Create `04-ISSUES/NNN-short-name/00-report.md`:
+
+   ```yaml
+   ---
+   status: open
+   opened: YYYY-MM-DD
+   located-in: []       # owning repo(s)/module(s), filled by diagnosis
+   fixed-by:            # PR or commit reference, filled at resolution
+   amended-design:      # design doc path, when the root cause was a design gap
+   ---
+   ```
+
+   Then the symptom **as observed**, in plain terms, with the evidence that it happened.
+2. Investigate in `01-diagnosis.md` in the same folder — the trail, dated, including what was
+   ruled out. Move `status:` to `diagnosing`, then `located` once the owner is known.
+3. Resolve. Set `status: resolved`, fill `fixed-by:`, and if the root cause was a design gap,
+   run playbook [02](02-graduation.md) and fill `amended-design:`.
+
+## Rules
+
+- Closed issues are never deleted — they are the mesh's symptom-to-component memory.
+- An issue whose answer is a general lesson should also be written to the knowledge base, so
+  the next person searching a symptom finds it. Both, not either.
+- `status: wontfix` is legitimate and requires a sentence saying why.