sow-tools/docs/agents/triage-labels.md

Issue and PR labels

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.

The rule

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.

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.

# 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.