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
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
-
Take the next free number. Create
04-ISSUES/NNN-short-name/00-report.md:--- 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.
-
Investigate in
01-diagnosis.mdin the same folder — the trail, dated, including what was ruled out. Movestatus:todiagnosing, thenlocatedonce the owner is known. -
Resolve. Set
status: resolved, fillfixed-by:, and if the root cause was a design gap, run playbook 02 and fillamended-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: wontfixis legitimate and requires a sentence saying why.