Skip to main content

​
Labels reference

The HAI-Co² label taxonomy is the connective tissue between Issues, PRs, the Project board, and the AI-automation workflows. This page is the canonical reference for what each label means and when to apply it. The labels themselves live in .github/labels.yml (the source of truth) and are created on the GitHub side by .github/scripts/init-labels.sh (idempotent, safe to re-run).

​
1. Triage rules (every label has a job)

  • Every Issue gets exactly one type: label during triage.
  • Every Issue gets exactly one area: label during triage.
    • On PRs, the labeler workflow auto-applies area:* based on changed paths, so you usually do not need to set it by hand on PRs.
  • needs-triage is removed once triage is done. Its presence on an open issue means “no maintainer has looked at this yet”.
  • good first issue is reserved for issues a newcomer can finish in under 2 hours without reading internal docs.
  • path:ai-automation is added explicitly by a maintainer, or automatically when Coco (HAI-Coco) is assigned to the issue. Default is traditional (the absence of any path:* label means traditional).
  • priority:* and effort:* are advisory, not contractual. Adjust them as your understanding of the work changes.

​
2. The full taxonomy

​
type:*: what kind of work this is

Pick exactly one. Drives the Release Drafter categories.

​
area:*: where in the codebase

Pick exactly one. The labeler workflow auto-applies these on PRs by matching changed paths to the labeler config. For cross-cutting changes (rare), apply the area you’d want a reviewer to care about first; mention the others in the PR body.

​
priority:*: how urgent

Apply during triage. Revisit if the situation changes.

​
status:*: workflow state

The Project board’s Status field is the primary place to read state. These labels exist for cases where a label is more ergonomic (search, filter dropdowns, mobile triage).

​
path:*: which development pathway

The single most consequential triage label. See ADR-0002. Apply exactly one engine label per issue (the bare path:ai-automation counts as the Copilot one); the chosen engine runs the whole PR through. See ai-pathway.md §2.4.

​
ai:*: AI review marker

The AI pathway is driven mostly by slash commands (/approve-plan, /coco, /promote dev), not labels, so there is just one ai:* label. The pathway and its workflows are documented in docs/ai-pathway.md.

​
stage:*: AI-pathway lifecycle (managed automatically)

Every AI-pathway issue and its PR carry exactly one stage:* label, advanced automatically by coco-stage-labels.yml as the assignee drives the flow, so the Issues and Pull-requests lists show where each item is at a glance. Never set these by hand. Warm colors (yellow/orange/green) mean it is your turn to act. See the state diagram in ai-pathway.md.

​
Community labels

​
effort:*: rough sizing

Advisory; the reviewer’s mental budget when they decide what to pick up this week.

​
skip-changelog: keep a PR out of the release notes

The escape hatch for PRs that must not appear in a release. Release Drafter reads it through its pre-exclude category, which drops the PR before the notes are generated and before the next version is resolved, so the PR neither shows up in the notes nor influences the version bump. Apply it by hand; nothing sets it automatically.

​
3. Adding or changing labels

The taxonomy is intentionally small. Before adding a label, ask:
  • Is this a new category, or could an existing label carry the signal?
  • Will this label be applied to ≥ 5 issues a year? If no, don’t add it: labels you never use are visual noise.
  • Does it conflict with the “exactly one type, exactly one area” rule? If yes, you are probably trying to model something else (e.g. the Project board’s Status field).
To add a label:
  1. Open a PR adding it to .github/labels.yml.
  2. Update this reference in the same PR.
  3. After merge, run .github/scripts/init-labels.sh (or wait for a maintainer to run it). The script is idempotent; existing labels’ colors/descriptions get updated to match the file.
To rename a label, prefer adding the new one + closing all open issues through the next triage to renaming in place: GitHub does support renames, but they invalidate every saved Project view filter, which is annoying for contributors.