Replace the stale triage label vocabulary with the org label taxonomy (#97)
`docs/agents/triage-labels.md` named five labels that do not exist in the tracker (`needs-triage`, `needs-info`, `ready-for-human`, `wontfix`). Meanwhile the org has an 18-label taxonomy at https://git.westgate.pw/org/ShadowsOverWestgate/settings/labels that agents never touched, because no doc pointed at it — `Kind/Bug` had been used twice across every repo. This replaces the doc with the real taxonomy and makes one `Kind/*` label required on every issue and PR at creation time. `AGENTS.md` gets the short version. Enforcement lands separately in `sow-platform` (`ops/policy/labels.yml` + a nightly `ops/checks/check-labels.sh` drift check). Identical doc change in every `sow-*` repo.Reviewed-on: #97 Co-authored-by: vickydotbat <vickydotbat@tutamail.com>
This commit was merged in pull request #97.
This commit is contained in:
@@ -94,9 +94,9 @@ Tests must survive harmless changes to constants, defaults, wording, ordering, f
|
||||
|
||||
Issues live in Gitea at git.westgate.pw (`ShadowsOverWestgate/sow-tools`), managed with the `tea` CLI. Issues follow ownership — file work in the repo that owns it, not the one you happen to be standing in. See `docs/agents/issue-tracker.md`.
|
||||
|
||||
### Triage labels
|
||||
### Labels
|
||||
|
||||
Default label vocabulary (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
|
||||
Every issue and PR gets exactly one org-wide `Kind/*` label at creation (`Kind/Bug`, `Kind/Feature`, `Kind/Enhancement`, `Kind/Documentation`, `Kind/Testing`, `Kind/Security`); `Priority/*`, `Status/*`, `Reviewed/*` and `Compat/Breaking` are optional. `tea issues create -L "Kind/Bug"`. See `docs/agents/triage-labels.md`.
|
||||
|
||||
### Domain docs
|
||||
|
||||
|
||||
@@ -1,15 +1,101 @@
|
||||
# Triage Labels
|
||||
# Issue and PR labels
|
||||
|
||||
The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker (Gitea — see `issue-tracker.md` for how to apply labels with `tea`).
|
||||
Labels are **org-wide**. They are defined once, for the whole
|
||||
`ShadowsOverWestgate` org, at
|
||||
<https://git.westgate.pw/org/ShadowsOverWestgate/settings/labels>, and every
|
||||
repo in the org can use them. Never create a per-repo copy of a label that
|
||||
already exists at org level.
|
||||
|
||||
| Label in mattpocock/skills | Label in our tracker | Meaning |
|
||||
| -------------------------- | -------------------- | ---------------------------------------- |
|
||||
| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue |
|
||||
| `needs-info` | `needs-info` | Waiting on reporter for more information |
|
||||
| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent |
|
||||
| `ready-for-human` | `ready-for-human` | Requires human implementation |
|
||||
| `wontfix` | `wontfix` | Will not be actioned |
|
||||
## The rule
|
||||
|
||||
When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
|
||||
**Every issue and every pull request gets exactly one `Kind/*` label, at the
|
||||
moment it is created.** Not later, not "when someone triages it". If you open
|
||||
it, you label it.
|
||||
|
||||
Edit the right-hand column to match whatever vocabulary you actually use.
|
||||
An issue with no `Kind/*` label is untriaged. That is the only meaning of
|
||||
"untriaged" here — there is no `needs-triage` label.
|
||||
|
||||
The other groups are optional, and each one is *exclusive*: an issue can carry
|
||||
at most one `Priority/*`, one `Status/*`, and one `Reviewed/*`. Gitea enforces
|
||||
this.
|
||||
|
||||
```sh
|
||||
# always from inside the owning repo's clone
|
||||
tea issues create --title "..." --description "..." --labels "Kind/Bug" </dev/null
|
||||
tea pr create --title "..." --description "..." --labels "Kind/Feature" </dev/null
|
||||
|
||||
# add a label to something that already exists
|
||||
tea api --method POST "repos/ShadowsOverWestgate/<repo>/issues/<n>/labels" \
|
||||
--data '{"labels":["Kind/Bug","Priority/High"]}'
|
||||
```
|
||||
|
||||
## Kind — what this is (pick exactly one)
|
||||
|
||||
| Label | Use it when |
|
||||
| -------------------- | --------------------------------------------------------------- |
|
||||
| `Kind/Bug` | Something that used to work, or is documented to work, does not |
|
||||
| `Kind/Feature` | New functionality that does not exist yet |
|
||||
| `Kind/Enhancement` | Existing functionality gets better, faster, or nicer |
|
||||
| `Kind/Documentation` | Docs, ADRs, runbooks, agent guides |
|
||||
| `Kind/Testing` | Tests, CI checks, contract scripts |
|
||||
| `Kind/Security` | Secrets, auth, permissions, hardening, a vulnerability |
|
||||
|
||||
Bug vs Enhancement, when it is unclear: if the current behaviour is wrong, it
|
||||
is a bug. If the current behaviour is right but weak, it is an enhancement.
|
||||
|
||||
## Priority — how urgent (optional, at most one)
|
||||
|
||||
`Priority/Critical`, `Priority/High`, `Priority/Medium`, `Priority/Low`.
|
||||
|
||||
Leave it off if you do not know. A wrong priority is worse than none.
|
||||
|
||||
## Status — why it is not moving (optional, at most one)
|
||||
|
||||
| Label | Meaning |
|
||||
| ----------------------- | -------------------------------------------- |
|
||||
| `Status/Blocked` | Waiting on another issue, PR, or decision |
|
||||
| `Status/Need More Info` | Waiting on the reporter or on a human answer |
|
||||
| `Status/Abandoned` | Work started and stopped; nobody is on it |
|
||||
|
||||
## Reviewed — the verdict (optional, at most one)
|
||||
|
||||
`Reviewed/Confirmed`, `Reviewed/Duplicate`, `Reviewed/Invalid`,
|
||||
`Reviewed/Won't Fix`. Apply one of these when closing without a fix, so the
|
||||
reason survives.
|
||||
|
||||
## Compat
|
||||
|
||||
`Compat/Breaking` — add it on top of the `Kind/*` label when the change breaks
|
||||
something that already works for a player, an operator, or another repo.
|
||||
|
||||
## Workflow labels (repo-level, not org-level)
|
||||
|
||||
These live in the repo, not the org, and are orthogonal to the groups above:
|
||||
|
||||
- `ready-for-agent` — the spec is complete; an AFK agent may pick this up.
|
||||
No label means it needs a human.
|
||||
- `wayfinder:map`, `wayfinder:task`, `wayfinder:research`,
|
||||
`wayfinder:prototype`, `wayfinder:grilling` — set by `/wayfinder`. Leave
|
||||
them alone unless you are running a wayfinder operation.
|
||||
- `sow-nodebb` also has `package/*` labels naming the plugin or theme a ticket
|
||||
touches.
|
||||
|
||||
## When a skill names a label we do not have
|
||||
|
||||
Skills written elsewhere (mattpocock/skills and friends) use a different
|
||||
vocabulary. Translate it:
|
||||
|
||||
| Skill says | Do this here |
|
||||
| ----------------- | ------------------------------------------------- |
|
||||
| `needs-triage` | Nothing — no `Kind/*` label already means this |
|
||||
| `needs-info` | `Status/Need More Info` |
|
||||
| `ready-for-agent` | `ready-for-agent` |
|
||||
| `ready-for-human` | Nothing — absence of `ready-for-agent` means this |
|
||||
| `wontfix` | `Reviewed/Won't Fix` |
|
||||
|
||||
## Drift check
|
||||
|
||||
`ops/checks/check-labels.sh` in `sow-platform` runs nightly. It compares the
|
||||
live org labels to `ops/policy/labels.yml` and lists every open issue and PR in
|
||||
the org that does not have exactly one `Kind/*` label. That check is the
|
||||
enforcement; this file is the rule.
|
||||
|
||||
Reference in New Issue
Block a user