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.
47 lines
1.8 KiB
Markdown
47 lines
1.8 KiB
Markdown
# 04-ISSUES
|
|
|
|
The front door for "something is wrong" at the level of the mesh's design or governance.
|
|
Diagnosis happens here, where the whole mesh is in view; the fix lands in the owning code
|
|
repository.
|
|
|
|
## What belongs here
|
|
|
|
| Belongs here | 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 owner 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*; an entry
|
|
there is an incident someone must *clear*. An issue whose answer is a general lesson belongs in
|
|
both.
|
|
|
|
## Structure
|
|
|
|
```
|
|
NNN-short-name/
|
|
00-report.md the symptom as observed, with the evidence; status in frontmatter
|
|
01-diagnosis.md the investigation trail, dated, including what was ruled out
|
|
```
|
|
|
|
## Frontmatter, on `00-report.md`
|
|
|
|
```yaml
|
|
---
|
|
status: open | diagnosing | located | resolved | wontfix
|
|
opened: YYYY-MM-DD
|
|
located-in: [] # owning repo(s) or module(s), filled by diagnosis
|
|
fixed-by: # pull request or commit reference, filled at resolution
|
|
amended-design: # design doc path, when the root cause was a design gap
|
|
---
|
|
```
|
|
|
|
## Rules
|
|
|
|
- Anyone may open an issue. No localisation is required to report one.
|
|
- The full flow is playbook [`00-META/process/03-issues.md`](../00-META/process/03-issues.md).
|
|
- Closed issues are never deleted — they are the mesh's symptom-to-component memory.
|
|
- `wontfix` is legitimate and requires a sentence saying why.
|