# Labels Reference

## Label Definitions

| Label | Use when issue involves... |
|-------|---------------------------|
| `bug` | Fixing something broken, errors, incorrect behavior |
| `enhancement` | New features, improvements to existing functionality |
| `deployment` | Hosting, CI/CD, Vercel, infrastructure, environment setup, domains, SSL |
| `documentation` | README, docs, comments, API documentation |
| `refactor` | Code cleanup, restructuring without changing behavior |
| `testing` | Adding/fixing tests, test infrastructure |
| `security` | Auth, API keys, vulnerabilities, permissions |
| `performance` | Speed improvements, optimization, caching |
| `design` | UI/UX changes, styling, layouts |
| `good first issue` | Simple, self-contained, good for newcomers |

## Selection Rules

1. Treat explicit user labeling instructions as authoritative.
2. When the repository uses this taxonomy, choose at most one issue-type label (`bug`, `enhancement`, `refactor`, `documentation`, `testing`) and add domain labels (`deployment`, `security`, `performance`, `design`) when they materially improve routing.
3. Add `good first issue` only when the work is genuinely small, self-contained, and documented.
4. If a needed label does not exist, include its exact definition in the approval preview before creating it.

## Auto-Detection Keywords

Use these keywords as hints when choosing labels:

| Keywords/Patterns | Label |
|-------------------|-------|
| bug, fix, broken, error, crash, failing, doesn't work | `bug` |
| feature, add, new, implement, enhance, improve, support | `enhancement` |
| deploy, vercel, hosting, CI/CD, environment, domain, SSL, infrastructure, production, server | `deployment` |
| docs, documentation, readme, comments, API docs, guide | `documentation` |
| refactor, cleanup, reorganize, restructure, simplify | `refactor` |
| test, spec, coverage, unit test, integration test, e2e | `testing` |
| security, auth, API key, token, permission, vulnerability, secret | `security` |
| performance, speed, optimize, cache, slow, fast, latency | `performance` |
| UI, UX, design, style, layout, responsive, mobile, CSS, theme | `design` |

Keyword matches are suggestions, not proof. Read the issue meaning before assigning labels.

## Creating Missing Labels

Map to the tracker's existing labels before proposing a new one: repositories and workspaces often have their own taxonomy (Linear workspaces start with `Bug`, `Feature`, and `Improvement`), and existing definitions take precedence. When the user approves creating one of these labels, use this description and color:

| Label | Description | Color |
|-------|-------------|-------|
| `bug` | Something is not working | `#D73A4A` |
| `enhancement` | New feature or improvement | `#A2EEEF` |
| `deployment` | Infrastructure and deployment tasks | `#0E8A16` |
| `documentation` | Documentation improvements | `#0075CA` |
| `refactor` | Code cleanup and restructuring | `#FBCA04` |
| `testing` | Tests and test infrastructure | `#BFD4F2` |
| `security` | Security-related changes | `#D93F0B` |
| `performance` | Performance improvements | `#5319E7` |
| `design` | UI/UX and styling | `#F9D0C4` |
| `good first issue` | Approachable for a first contribution | `#7057FF` |

Create only the labels the user approved; the tracker reference has the command or tool to use.