# 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.