From f395d86db5445cb62b6540514e44cce7a1defd91 Mon Sep 17 00:00:00 2001 From: vickydotbat Date: Tue, 4 Aug 2026 21:55:47 +0000 Subject: [PATCH] Replace the stale triage label vocabulary with the org label taxonomy (#97) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `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: https://git.westgate.pw/ShadowsOverWestgate/sow-tools/pulls/97 Co-authored-by: vickydotbat --- AGENTS.md | 4 +- docs/agents/triage-labels.md | 108 +++++++++++++++++++++++++++++++---- 2 files changed, 99 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1f6a7f5..c35d169 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md index d8bfed9..f5408bc 100644 --- a/docs/agents/triage-labels.md +++ b/docs/agents/triage-labels.md @@ -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 +, 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" /issues//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.