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:
@@ -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