1 files changed, 74 insertions, 0 deletions
diff --git a/debug/issue/README.md b/debug/issue/README.md
new file mode 100644
index 0000000..2c08afc
--- /dev/null
+++ b/debug/issue/README.md
@@ -0,0 +1,74 @@
+# Issue register — process
+
+**Policy: do NOT create issues by default.** An issue here is a *nasty bug*:
+something that blocks mission-critical behaviour, is non-deterministic or not
+reproducible on demand, corrupts state, or spans subsystems such that a
+single-session fix is unrealistic. Ordinary fixes, TODOs and feature work do
+not get an issue — they live in the handoff and the code comments.
+
+File an issue when **any** of these holds:
+
+1. Reproducibility / liveness is variable (works sometimes, stalls others)
+   and the variance itself is the bug.
+2. The failure blocks a 1.0 acceptance criterion (guest CUDA, multi-VM,
+   performance target, ...).
+3. Cross-subsystem state (host module + guest driver + physical GPU +
+   userspace tools) is involved and the ownership of the fix is unclear.
+4. The investigation has already burned more than one session without a
+   confirmed root cause.
+
+## How to file
+
+* Directory: `open-iov/debug/issue/`; solved ones move to
+  `open-iov/debug/issue/solved/` (never delete, never renumber).
+* Filename: `issue-number-N.md` with the next free integer `N`
+  (`issue-number-1.md`, `issue-number-2.md`, ...). Create
+  `issue-number-N+1.md` as a copy of the template below — do not create
+  placeholder issues.
+* Keep it **public-safe** (this directory is tracked): describe components,
+  behaviour and evidence (same rules as every tracked document).
+* Reference evidence by artifact: session/log file names, counter lines,
+  commit hashes. Every claim needs its evidence pointer.
+
+## Template
+
+```markdown
+# ISSUE-00NN: <one-line title>
+* Status: OPEN | FIX IMPLEMENTED (VALIDATION PENDING) | SOLVED
+* Filed: <date>, session <label> | Priority: <top/p1/p2> | Component: <kernel/guest/...>
+
+## Symptom
+What is observed, by whom, how often. Include the exact observable signature.
+
+## Impact
+Which acceptance criterion is blocked; what work is blocked behind it.
+
+## Evidence
+Logs/counters/commits that establish the facts. Include the one-line
+discriminators between healthy and failing runs.
+
+## Root cause
+The causal chain established so far, with confidence and what is still
+hypothesis (label uncertainty explicitly).
+
+## Fix / fix plan
+Code changes with commit hashes; for open items, the ordered plan and the
+files/functions to touch.
+
+## Validation plan
+Acceptance criteria (numbers of consecutive runs, counters that must stay
+zero, suites to run) and how the fix is rolled back if it regresses.
+
+## History
+Dated one-liners: what was tried, what it taught, what was rejected.
+```
+
+## Lifecycle
+
+* OPEN: filed, root cause partial.
+* FIX IMPLEMENTED (VALIDATION PENDING): code landed (committed) but the
+  acceptance runs have not completed on a live stack.
+* SOLVED: acceptance criteria met with evidence; move the file to `solved/`
+  and add a `## Resolution` section (what fixed it, the validating runs,
+  residual risks). If the same failure returns, file a **new** number and
+  cross-reference — do not reopen the moved file.