Skip to content

labels.md

Latest commit

 

History

History
287 lines (198 loc) · 8.43 KB

labels.md

File metadata and controls

287 lines (198 loc) · 8.43 KB

Label Governance

Purpose

This document defines the default Linear label taxonomy for AI-assisted engineering workflows. The goal is to keep labels small, explicit, and operationally useful.

The system of record is Linear. This document defines only Linear label surfaces and the default issue shape inside Linear.

Default Surfaces

Team-Level Issue Labels

This is the primary surface.

Use team-level issue labels for the main working taxonomy:

  • repo:*
  • kind:*
  • area:*
  • theme:*

status:* is not a default axis. Only use it as a narrow exception when a built-in field is not sufficient.

Workspace-Level Issue Labels

Default to none.

Only create workspace-level issue labels when the same label is:

  • truly cross-team
  • long-lived
  • semantically identical in every team that uses it

If a label exists only to help one team operate, it belongs at team scope.

Project Labels

Default to none.

Only use project labels for portfolio-level grouping across multiple projects, for example:

  • a program
  • a track
  • a company-wide initiative

Do not use project labels for repo ownership, issue type, or technical area.

Source Of Truth

  • Linear is authoritative for label semantics.
  • Built-in Linear fields remain authoritative for workflow state.
  • Labels exist to add missing semantics, not to duplicate built-in fields.

Working Model

  • Team-level issue labels are the main operating surface.
  • The default issue model uses four axes: repo:*, kind:*, area:*, and theme:*.
  • repo:* and kind:* are hard routing axes.
  • area:* and theme:* are soft semantic axes.

Core Rules

  • One concept, one home.
  • Implementation issues must have exactly one repo:* label.
  • One issue must have exactly one kind:* label.
  • Treat repo:* and kind:* as hard routing axes.
  • Treat area:* and theme:* as soft semantic axes. Keep them sparse, stable, and reusable.
  • Do not use labels to restate built-in fields such as priority, assignee, project, cycle, or team.
  • Every label should have a short description that explains its intended use.
  • Prefer low-cardinality labels with durable meaning.
  • Do not add a fifth default axis unless built-in fields and the four default axes are both insufficient.
  • Delete or merge zero-use and duplicate labels during maintenance.

Canonical Axes

repo:*

Repository ownership or implementation surface.

This axis is for issues that primarily belong to one repository.

Examples:

  • repo:pubfi-mono
  • repo:maestro
  • repo:rsnap

If an issue is team-level governance, portfolio planning, or other meta work that is not primarily owned by one repository, it may omit repo:*.

If an implementation issue spans multiple repositories, do not add multiple repo:* labels. Pick one primary owning repository and split follow-on work into linked issues when the execution would otherwise be ambiguous.

Do not expand repo:* into package, module, service, or temporary execution surface labels. Those belong in area:* or the issue body.

kind:*

What kind of work the issue is.

Recommended set:

  • kind:arch - architecture and system-shape changes
  • kind:bug - defect or behavioral fix
  • kind:chore - maintenance work that is not better expressed elsewhere
  • kind:epic - large umbrella or coordinating issue
  • kind:feat - new capability or product behavior
  • kind:perf - performance or efficiency improvement
  • kind:research - investigation, evaluation, or spike
  • kind:spec - contract, schema, or design definition

Keep this set closed by default. Add a new kind:* only when repeated triage shows a durable ambiguity that cannot be resolved with the existing set.

Only one kind:* label is allowed per issue.

If an issue could fit multiple kinds, choose the primary execution intent:

  • feat if the main work is delivering a new capability
  • bug if the main work is correcting broken behavior
  • arch if the main work changes system shape, boundaries, or ownership
  • spec if the main deliverable is a contract or design definition
  • perf if the main result is lower latency, lower cost, or higher throughput
  • research if the main result is a decision memo, evaluation, or spike
  • chore only when none of the above fits cleanly
  • epic only for umbrella coordination issues

If secondary semantics still matter, express them in area:*, theme:*, or the issue body instead of adding a second kind:*.

area:*

Where the work lands technically or organizationally.

This is a soft axis.

Keep area:* small and durable. Use it for stable domains, not temporary components, one-off migrations, or incident-specific labels.

Examples:

  • area:api
  • area:search
  • area:refinery
  • area:orchestration

theme:*

Why the work matters from a strategic or operational perspective.

This is a soft axis.

Keep theme:* sparse and long-lived. Use it for durable strategic reasons, not short-term campaigns, quarter-specific pushes, or temporary operating language.

Examples:

  • theme:reliability
  • theme:governance
  • theme:cost
  • theme:evaluation
  • theme:provenance

status:*

This is a rare exception axis, not part of the default issue shape.

Use only when built-in workflow states are insufficient.

Good examples are narrow operator states that do not belong in the main Linear status machine.

Recommended Defaults

For implementation issues, the default issue shape should be:

  • exactly one repo:*
  • exactly one kind:*
  • zero or more area:*
  • zero or more theme:*

For meta issues that are not owned by one repository, the default issue shape should be:

  • no repo:*
  • exactly one kind:*
  • zero or more area:*
  • zero or more theme:*

For most teams, the default project shape should be:

  • no project labels

For most workspaces, the default workspace shape should be:

  • no workspace-level issue labels

Naming Rules

  • Use lowercase.
  • Use a stable axis prefix followed by a colon.
  • Keep names short and literal.
  • Do not encode multiple concepts into one label.

Good:

  • kind:feat
  • repo:maestro
  • theme:reliability

Bad:

  • backend-bug
  • urgent-search-fix
  • maestro-and-runtime

Description Rules

  • Every label should have a non-empty description.
  • The description should be one short sentence.
  • The description should state scope and intended use, not process history.

Good:

  • Issues that belong to the pubfi-mono repository.
  • New capability or product behavior that is not primarily a refactor or cleanup.

Bad:

  • Imported from old system
  • Temporary label for migration
  • Used sometimes for backend issues

Anti-Patterns

  • The same label split across workspace and team scope.
  • Multiple kind:* labels on one issue.
  • Forcing repo:* onto non-repo meta work.
  • Growing repo:* into package, module, or service labels.
  • Using project labels for issue taxonomy.
  • Using labels to mirror built-in Linear fields.
  • Using area:* or theme:* for short-lived initiatives or one-off tickets.
  • Creating one-off labels for a single incident or ticket.
  • Keeping migration leftovers or labels that no longer drive any view or rule.

Change Policy

Before creating a new label, ask:

  1. Is this concept already covered by a built-in field?
  2. Is this concept already covered by an existing label?
  3. Will more than a handful of issues use this label over time?
  4. Is the label stable enough to survive refactors and org changes?
  5. Which surface should own this label: team-level issue labels, workspace-level issue labels, project labels, or nowhere?
  6. Does this belong inside repo:*, kind:*, area:*, theme:*, the narrow status:* exception, or the issue body instead of creating a new default axis?

If questions 1 through 4 are not all yes, or questions 5 and 6 do not have one clear answer, do not add the label yet.

Review Checklist

When auditing a team's labels:

  1. Remove scope duplication first.
  2. Delete or demote any workspace-level issue label that is not truly cross-team, long-lived, and semantically identical everywhere it appears.
  3. Remove zero-use labels next.
  4. Normalize every implementation issue to one repo:* and one kind:*.
  5. Normalize every meta issue to no repo:* and exactly one kind:*.
  6. Review area:* and theme:* only after the core axes are clean, and delete one-off soft-axis labels.
  7. Re-justify every status:* label as a live narrow exception, or delete it.
  8. Confirm every label has a useful description.
  9. Keep project labels empty unless there is a real portfolio need.