---
type: types/instruction.md
name: issue-tracking
description: Where open work on this stack is tracked, and what the prio/ and size/ labels on a Gitea issue mean.
---
# Track open work as Gitea issues, not as prose in the repo

Open work on this stack lives at
<https://gitea.nehmer.net/torben/chemenu/issues>, one issue per work
package, and nowhere else. There is no `TODO.md`; there was, and every item in
it either became an issue or was already one, described twice.

That is the whole reason for this file: a second list is a second thing to
maintain, and the one that drifts is always the one nobody reads first. The
issue tracker wins that comparison outright - it has state, comments, labels,
and a link that survives the change it describes. A markdown file in the repo
has none of it, and it costs a publish to touch.

This instruction exists only in the dev repo. A distributed instance has no
issues at that URL, which is exactly why `dist export` excludes
`instructions/dev/` wholesale (see [tools/CONTRACT.md](../../tools/CONTRACT.md)).

## When to run

- Something is worth doing but not now. Open an issue; do not write it down in
  the repo.
- A session's findings outgrow the change it was making - a gap in the tooling,
  an assumption nobody has checked, a decision that needs the user.
- Prioritising: deciding what to pick up next, or re-labelling after the ground
  moved.

## Steps

1. **Write the issue so it survives without you.** What is broken or missing,
   why it matters, what "done" looks like as acceptance criteria, and the
   specific files or commands involved. An issue that only makes sense to
   whoever wrote it is a note, and notes were the problem.

2. **Give it exactly two labels: one `prio/`, one `size/`.** Both, always -
   a priority without a cost is half a decision. Neither is a promise about
   *when*; together they answer "what should I pick up in the time I have".

   | Priority | Means |
   |---|---|
   | `prio/1` | Blocks or damages work in progress. Next. |
   | `prio/2` | Accrues interest. Planned. |
   | `prio/3` | Worth doing, waiting on a trigger. |

   `prio/3` is not a graveyard. It means the issue's value is real but gated on
   something outside it - a decision, another issue, a second instance
   existing. Name that trigger in the issue, or the label is a polite no.

   | Size | Means |
   |---|---|
   | `size/XS` | Minutes. Often just a decision or an observation to record. |
   | `size/S` | One session, one publish, a clear cut. |
   | `size/M` | Several files; a contract or instruction change; its own test effort. |
   | `size/L` | Several sessions, or open design questions before the first commit. |

   Size is effort, not importance. A `prio/1 size/XS` is the best thing on the
   board; a `prio/3 size/L` is a thing to talk about before anyone starts.

3. **Re-label when the ground moves, and say why in a comment.** A trigger that
   fired turns `prio/3` into `prio/2`. A design question that got answered can
   drop a size. Silent re-labelling is how a board stops meaning anything.

4. **Close with what actually happened**, not with a commit hash alone: which
   proposals were implemented, which were deliberately left out and why, and
   what was verified. The issue is the only place that record survives - a
   changelog entry says what changed, not what was decided against.

## Decision points

- **Issue or changelog?** An issue is work that is *not done*. `CHANGES.md` is
  what shipped. A finished change needs both: the entry, and the issue closed
  with the reasoning.
- **Issue or `kb/` page?** An issue is about *this stack* and is ephemeral - it
  closes. A `kb/` page is compiled knowledge that stays true. Never put wiki
  content findings in an issue, and never file a work item as a page.
- **Two labels feel too coarse?** They are meant to. A third axis - kind, area,
  status - is the point at which a taxonomy starts needing maintenance of its
  own, and this board has one maintainer.