feat: Issue-Board auf vier Pflicht-Label-Familien und Body-als-Wahrheit (#41)
CI / verify (push) Successful in 53s
Release / release (push) Successful in 39s

Files changed:
- CHANGES.md
- VERSION
- instructions/dev/issue-tracking.md
- instructions/dev/stack-dev/SKILL.md
This commit is contained in:
2026-09-02 23:11:48 +02:00
parent 3f99d6715f
commit c8c238523a
4 changed files with 133 additions and 26 deletions
+91 -23
View File
@@ -1,7 +1,7 @@
---
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.
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
@@ -26,6 +26,8 @@ issues at that URL, which is exactly why `dist export` excludes
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.
@@ -36,35 +38,96 @@ issues at that URL, which is exactly why `dist export` excludes
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".
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.
| Priority | Means |
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 |
|---|---|
| `prio/1` | Blocks or damages work in progress. Next. |
| `prio/2` | Accrues interest. Planned. |
| `prio/3` | Worth doing, waiting on a trigger. |
| `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. |
`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
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/` | 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.
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.
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.
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.
4. **Close with what actually happened**, not with a commit hash alone: which
| `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.
@@ -75,8 +138,13 @@ issues at that URL, which is exactly why `dist export` excludes
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.
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.