--- type: types/instruction.md name: issue-tracking description: Where open work on this stack is tracked, what the four mandatory area/kind/prio/size labels and the two status flags on a Gitea issue mean, and how to keep an issue body current across sessions. --- # Track open work as Gitea issues, not as prose in the repo Open work on this stack lives at , 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. - Picking an issue up: before doing anything else, read the body as the current spec, and re-label it if the ground has moved since. - 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. **Treat the body as the current truth, not as a historical first post.** Work on one issue spans several sessions, often weeks apart, and the body is the only thing that connects them: a session opening the issue must be able to reconstruct what is decided and what is still open from the body alone, without a human re-explaining it. So when the state changes, **rewrite the body** - do not append to a text that has become wrong. An additively grown log forces every later reader to reconstruct the current state by filtering the whole history. Body rewrites and comments are an LLM session's job. A human normally touches only labels and metadata directly. 3. **Comment a changelog, never a copy.** Every body rewrite gets one short comment naming only what changed against the previous state - what is new, what is gone, what was corrected. Do not snapshot the old body into a comment: a full copy per revision forces a human to diff two prose texts, which is not a readable history, only another copy. ``` **Changelog:** Decision 2 tightened - `kind/` may now change over an issue's life. Old acceptance criterion 3 dropped (covered by #42). ``` 4. **Give it all four mandatory labels: one `area/`, one `kind/`, one `prio/`, one `size/`.** All four, always. Machine maintenance by an LLM session is what makes four axes affordable - the original objection to a third and fourth axis was the upkeep cost for a single human maintainer, and that objection no longer holds. | `area/` | Means | |---|---| | `area/kb` | The `kb/` schema, contract, confidence machinery, lint - the knowledge base as a system. | | `area/distribution` | Shipping, upgrading and versioning an instance. | | `area/corpus` | The content and scope of `kb/` in this instance, and the demo/testbed question. | | `area/workflow` | Git, merging, branching, publish, PRs. | | `area/process` | The development process itself, rather than the stack as an artefact. | There is deliberately no `area/tools`: tooling is filed under the domain it serves, not under where its code sits. The axis follows the stage split in [AGENTS.md](../../AGENTS.md). | `kind/` | Means | |---|---| | `kind/decision` | Waiting on an operator decision. | | `kind/build` | Specified; waiting only on implementation time. | | `kind/defect` | A finding: documentation and reality, or two documents, contradict each other. | `kind/` is expected to change over an issue's life - `decision` becomes `build` once the decision is made. That is session memory working, not a labelling failure. | `prio/` | Means | |---|---| | `prio/blocking` | Blocks or damages work in progress. Next. | | `prio/planned` | Accrues interest. Planned. | | `prio/waiting` | Worth doing, waiting on a trigger. | `prio/waiting` 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/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/blocking size/S` is the best thing on the board; a `prio/waiting size/L` is a thing to talk about before anyone starts. 5. **Add a `status/` flag only when it applies.** Both are optional, because each describes a temporary condition rather than a property every issue has. | `status/` | Means | |---|---| | `status/blocked` | Waiting on another, still-open issue - not workable on its own, whatever its `prio/` says. Name the blocking issue in the body. | | `status/unconfirmed` | A reported suspicion, not yet checked against actual behaviour. Applies to any `kind/`, not just `kind/defect`. | While `status/unconfirmed` is set, `size/` and `prio/` are provisional. Triage ends it one of two ways: the flag comes off and `size`/`prio` are set for real, or the issue is closed with the reason. An unverified suspicion does not stay open indefinitely - the process-level analogue of AGENTS.md invariant 3. 6. **Re-label when the ground moves, and say why in a comment.** A trigger that fired turns `prio/waiting` into `prio/planned`. A design question that got answered can drop a size and move `kind/decision` to `kind/build`. Silent re-labelling is how a board stops meaning anything. 7. **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, and it records a wish. A `kb/` page is verified knowledge that stays true. Never put wiki content findings in an issue, and never file a work item as a page. - **Rewrite the body, or add a comment?** Rewrite whenever a reader of the body alone would otherwise be misled - a changed decision, a dropped criterion, a new constraint. A comment carries the changelog line for that rewrite, and nothing else that a future session needs in order to act. - **An old issue carries only `prio/` and `size/`?** Complete it to all four when you touch it, rather than in a sweep. The board reaches the new scheme issue by issue, as each is picked up.