---
summary: "Issue labeling policy for triage, prioritization, and backlog hygiene."
read_when:
  - Triageing GitHub issues
  - Adding or updating issue labels
  - Organizing the backlog
---

# Issue labeling guide

This repo uses labels to make the issue tracker easier to scan by:

- **type** — what kind of issue is this?
- **priority** — how urgent is it?
- **area** — what subsystem is affected?
- **provider** — which provider/service is involved?
- **workflow state** — what kind of follow-up is needed?

The goal is not to perfectly label everything. The goal is to make open issues easy to sort into:

- what is broken now,
- what needs maintainer attention,
- what is accepted backlog,
- and what belongs to a specific provider or subsystem.

## Labeling rules

For most open issues, aim to apply:

- **1 type label**
- **1 priority label**
- **1 workflow label**
- **1 area label**
- **0–1 provider labels**

That means most issues should end up with **3–5 labels max**.

## Type labels

Use the existing GitHub-style labels:

- `bug` — broken behavior, crash, mismatch, false negative, bad parsing, auth failure
- `enhancement` — feature request, UX improvement, support for a new workflow
- `documentation` — docs, onboarding, missing setup guidance
- `question` — only for issues that are primarily asking for clarification or support

Avoid using `question` as a generic fallback when the issue is actually a bug or feature request.

## Priority labels

- `priority:high` — crashes, install failures, auth/account breakage, provider unusable, severe resource issues
- `priority:medium` — real issue or good feature request, but not urgent
- `priority:low` — minor polish, optional UX improvements, long-tail backlog

## Workflow labels

- `needs-triage` — new issue that has not been categorized yet
- `needs-repro` — needs logs, screenshots, exact steps, or a current repro
- `needs-design` — valid request, but needs a product/UX decision before implementation
- `blocked-upstream` — likely caused or limited by upstream provider behavior
- `accepted` — intentionally kept open as part of the backlog/roadmap

## Area labels

- `area:auth-keychain` — keychain prompts, login state, token refresh, account switching
- `area:install-distribution` — Homebrew, packaging, launch/install failures, binary detection
- `area:usage-accuracy` — usage %, reset windows, plan parsing, cost/token math
- `area:performance` — CPU, battery, memory, background sessions/process churn
- `area:ui-ux` — menu bar behavior, settings, copy, visual layout, interaction polish
- `area:widget` — widget registration, app groups, widget gallery visibility
- `area:docs-onboarding` — setup docs, onboarding docs, missing instructions
- `area:notifications` — threshold alerts, prompt waiting, quota notifications
- `area:export-integration` — Prometheus, HTTP server mode, external integrations
- `area:accounts` — multiple accounts, account discovery, account switching UX

## Provider labels

Only apply one when a provider is clearly the main subject:

- `provider:claude`
- `provider:codex`
- `provider:cursor`
- `provider:copilot`
- `provider:gemini`
- `provider:alibaba`
- `provider:factory`
- `provider:antigravity`
- `provider:opencode`
- `provider:zai`
- `provider:openrouter`

Not every issue needs a provider label.

## Close-time labels

These are mostly useful when resolving issues, not as backlog-organizing labels:

- `duplicate`
- `invalid`
- `wontfix`
- `stale`

## Recommended minimum viable label set

If starting from a sparse tracker, add these first:

### Priority
- `priority:high`
- `priority:medium`
- `priority:low`

### Workflow
- `needs-triage`
- `needs-repro`
- `needs-design`
- `accepted`

### Area
- `area:auth-keychain`
- `area:install-distribution`
- `area:usage-accuracy`
- `area:performance`
- `area:ui-ux`
- `area:widget`
- `area:docs-onboarding`

### Provider
- `provider:claude`
- `provider:codex`
- `provider:cursor`
- `provider:copilot`

This smaller set already gives most of the value.

## Examples

### Example 1 — severe Claude keychain issue
Issue: repeated Claude keychain prompts, user can’t keep the app running normally.

Suggested labels:
- `bug`
- `priority:high`
- `area:auth-keychain`
- `provider:claude`

### Example 2 — roadmap feature
Issue: multiple account support.

Suggested labels:
- `enhancement`
- `priority:high`
- `area:accounts`
- `needs-design`

### Example 3 — needs better repro
Issue: generic usage mismatch with unclear screenshots and no exact values.

Suggested labels:
- `bug`
- `priority:medium`
- `area:usage-accuracy`
- `needs-repro`

### Example 4 — accepted backlog UI request
Issue: show burn rate / pacing indicators.

Suggested labels:
- `enhancement`
- `priority:medium`
- `area:usage-accuracy`
- `accepted`

## Suggested rollout

1. **Create the new labels**
2. **Backfill the top-priority open issues first**
   - all `priority:high` bugs
   - major roadmap items
   - maintainer-triage issues
3. **Apply labels to new issues at intake**
4. **Backfill older backlog issues gradually**

## Practical guidance

- Prefer **fewer, clearer labels** over many vague labels.
- Do not label everything `question`.
- Do not use both `needs-repro` and `accepted` on the same issue unless there is a strong reason.
- If an issue is provider-specific, add the provider label early.
- If an issue is obviously real and intended to stay open, add `accepted` so it doesn’t look abandoned.

## Current workflow-specific labels

These already exist and should stay scoped to their current purpose:

- `upstream-sync`
- `needs-review`
- `changes requested`

They should not replace the general issue triage labels above.