---
name: hq-new-issue
description: Use when something is wrong with the mesh at the level of design or governance — a rule enforced by nothing, a stated behaviour that does not happen, a failure the design lets pass silently. Triggers on "this is broken", "open an issue", "that rule isn't enforced", "this reports success and does nothing".
---

# hq-new-issue

Opens a numbered issue. **Authoritative playbook:**
[`00-META/process/03-issues.md`](../../../00-META/process/03-issues.md).

## First, decide it belongs here

| 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 |
| Finding the owner needs the whole mesh in view | Symptom → fix, once the answer is known |

**Search the knowledge base first** for the literal symptom text. If the answer is already
there, this is not an issue — it is a lookup. If the answer is a general lesson, it belongs in
both.

## Steps

1. Next free number. Create `04-ISSUES/NNN-short-name/00-report.md` with:

   ```yaml
   ---
   status: open
   opened: YYYY-MM-DD
   located-in: []
   fixed-by:
   amended-design:
   ---
   ```

2. Write the symptom **as observed**, in plain terms, with the evidence that it happened —
   what was run, what came back, when.
3. Say why it matters beyond the instance. An issue that is only one occurrence is a knowledge
   base entry.
4. End with open questions rather than a proposed fix. Diagnosis is a separate step.

## Do not

- Do not name nodes, domains, addresses or paths. This repository is public.
- Do not guess the owner — `located-in:` is filled by diagnosis, not by opening.