hq/04-ISSUES

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
  01-diagnosis.md   the investigation trail, dated, including what was ruled out

NNN is the number the issue tracker gave. The issue's status, owner (located-in), fix (fixed-by), design amendment and replay live in the tracker — issue-tracker.get NNN — not here (ADR 0275).

Frontmatter, on 00-report.md

---
opened: YYYY-MM-DD
---

The report's first heading is # NNN. The title, the title the tracker holds. A report carries no status:, located-in:, fixed-by:, amended-design:, replay: or replay-none:; cycle.py refuses them. The folders numbered 001 to 364 carried them until the import of slice 3 had taken them into the tracker; what they said then is in this repository's history at the commit the import read, which every imported issue names.

A folder here keeps the public narrative of a design or governance issue. A plain bug needs no folder: it is whole in the tracker.

Rules

• Anyone may open an issue. No localisation is required to report one.
• The full flow is playbook 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.