feat: Issue-Board auf vier Pflicht-Label-Familien und Body-als-Wahrheit (#41)
Files changed: - CHANGES.md - VERSION - instructions/dev/issue-tracking.md - instructions/dev/stack-dev/SKILL.md
This commit is contained in:
+38
@@ -20,6 +20,44 @@ their date-only headings.
|
||||
|
||||
---
|
||||
|
||||
## 4.0.1 - 2026-09-02 - Issue-Board: vier Pflicht-Label-Familien und Body-als-Wahrheit
|
||||
|
||||
**Author:** Torben Nehmer
|
||||
|
||||
Das Issue-Schema aus 1.2.1 hatte zwei Pflichtachsen und einen ausdrücklich begründeten Verzicht
|
||||
auf eine dritte: eine Taxonomie mit mehr Achsen brauche eigene Pflege, und das Board habe einen
|
||||
einzigen Betreuer. Diese Begründung ist entfallen, weil die Pflege inzwischen maschinell
|
||||
passiert - Body-Rewrites und Kommentare laufen über eine LLM-Sitzung, Menschen fassen in der
|
||||
Regel nur Labels an. Damit sind vier Achsen bezahlbar (Issue #41).
|
||||
|
||||
**Pflicht auf jedem offenen Issue sind jetzt vier Label:** `area/` (`kb`, `distribution`,
|
||||
`corpus`, `workflow`, `process` - kein `area/tools`, Tooling wird nach der bedienten Domäne
|
||||
einsortiert, nicht nach Codeort), `kind/` (`decision`, `build`, `defect`), `prio/`
|
||||
(`blocking`, `planned`, `waiting` - reine Umbenennung von `1`/`2`/`3`) und `size/` (`S`, `M`,
|
||||
`L`; `XS` entfällt). Dazu zwei optionale Flags: `status/blocked` für Abhängigkeit von einem
|
||||
anderen offenen Issue, `status/unconfirmed` für einen ungeprüften Verdacht, unter dem `size`
|
||||
und `prio` vorläufig sind. Ein `unconfirmed`-Issue endet in der Triage entweder ohne Flag und
|
||||
mit verbindlichen Werten oder geschlossen mit Begründung - die Prozessentsprechung zu
|
||||
Invariante 3.
|
||||
|
||||
**Der Issue-Body ist ab jetzt aktuelle Wahrheit, nicht Ursprungstext.** Die Umsetzung eines
|
||||
Issues zieht sich über mehrere, zeitlich getrennte Sitzungen, und der Body ist das einzige, was
|
||||
sie verbindet: eine Sitzung muss aus ihm allein rekonstruieren können, was entschieden und was
|
||||
offen ist. Er wird deshalb umgeschrieben statt ergänzt. Jeder Rewrite bekommt einen Kommentar,
|
||||
der ausschließlich benennt, was sich geändert hat - keine Vollkopie des alten Stands, weil ein
|
||||
Mensch zwei Fließtexte nicht diffen kann und eine Kopie pro Revision damit keine Historie ist,
|
||||
sondern nur eine weitere Kopie.
|
||||
|
||||
Geändert: [instructions/dev/issue-tracking.md](instructions/dev/issue-tracking.md) (Schritte 2,
|
||||
3, 5 neu; Schritt 4 um `area/` und `kind/` erweitert; der Entscheidungspunkt „Two labels feel
|
||||
too coarse?" entfällt) und die Beschreibungszeile in `instructions/dev/stack-dev/SKILL.md`. Für
|
||||
eine ausgelieferte Instanz ändert sich nichts: `dist export` schließt `instructions/dev/`
|
||||
vollständig aus, weshalb dies ein PATCH ist und kein MINOR - dieselbe Begründung wie bei
|
||||
`1.2.1`. Noch offen aus #41: `kb/concepts/Issue Label Scheme.md` beschreibt weiterhin das
|
||||
zweiachsige Schema und braucht eine eigene `wiki-manage`-Sitzung.
|
||||
|
||||
---
|
||||
|
||||
## 4.0.0 - 2026-09-02 - Prosa ist kein Identifier: Link-Taxonomie als Enum, generierte Regionen mit Markern
|
||||
|
||||
**Author:** Torben Nehmer
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -43,8 +43,9 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
|
||||
engineering, memory and deploy-time learning; consult before a design decision in those
|
||||
areas.
|
||||
[issue-tracking.md](../issue-tracking.md) - open work lives in Gitea issues, one per work
|
||||
package, labelled `prio/1..3` and `size/XS..L`. There is no `TODO.md`. Read it before
|
||||
filing something for later, or before deciding what to pick up next.
|
||||
package, labelled `area/`, `kind/`, `prio/` and `size/`, with the body kept as the current
|
||||
truth rather than as a first post. There is no `TODO.md`. Read it before filing something
|
||||
for later, before editing an issue, or before deciding what to pick up next.
|
||||
[testing-conventions.md](../testing-conventions.md) - the suite runs against a deliberately
|
||||
empty machine; what the autouse fixture already neutralizes, and what a test still has to
|
||||
establish itself. Read it before adding or changing a test.
|
||||
|
||||
Reference in New Issue
Block a user