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