# Labels Pysae — GitLab Taxonomy

Edit this file to update the label taxonomy used in ticket generation.

## Domain labels (application layer, required)

At least one required per ticket.

| Label    | Scope                                    |
|----------|------------------------------------------|
| `~API`   | Backend API (FastAPI, endpoints, models)  |
| `~Op`    | Operator dashboard                       |
| `~Driver`| Driver mobile app (Capacitor)            |
| `~Editor`| Route/schedule editor                    |
| `~Info`  | Passenger information system             |
| `~Infra` | Infrastructure, CI/CD, deployment        |
| `~Screen`| Screen/display systems                   |
| `~Website`| Marketing website (Next.js / next-intl)  |
| `~Shift` | Shift platform (pysae/shift)             |

## Type labels (required)

Exactly one per ticket.

| Label                | Usage                                                                                                                                  |
|----------------------|----------------------------------------------------------------------------------------------------------------------------------------|
| `~type::bug`         | Defect, regression, incorrect behavior                                                                                                 |
| `~type::feature`     | New user-facing functionality, user story. **Never** for tooling, scripts, CLI, or internal dev utilities — those are `type::technical` |
| `~type::technical`   | Tech debt, tooling, scripts, CLI commands, migrations, infra, internal dev utilities                                                   |
| `~type::refactoring` | Refactoring                                                                                                                            |

## Priority labels (optional)

| Label            | Criteria                                        |
|------------------|-------------------------------------------------|
| `~priority::P1`  | Blocking production, data loss risk, SLA breach |
| `~priority::P2`  | Significant impact, workaround exists            |
| `~priority::P3`  | Low urgency, improvement, nice-to-have           |

## Gitflow labels (deprecated, should not be used)

Default is feature if absent.

| Label               | Usage                                       |
|---------------------|---------------------------------------------|
| `~gitflow::feature` | Standard feature branch workflow             |
| `~gitflow::hotfix`  | Critical fix deployed directly to production |

## Board column labels (workflow, required)

These labels control the column on the [Pysae board](https://gitlab.com/groups/pysae/-/boards/546268).
**Every issue MUST have exactly one board column label** so it appears in the correct column on the board. Without a board label, the issue falls into the Open/Backlog list and is effectively invisible.

| Label                       | Board column | When to use                                                                                        |
|-----------------------------|--------------|----------------------------------------------------------------------------------------------------|
| `~"workflow::Refinement"`   | Refinement   | Issue needs discussion, scoping, or design before it can be worked on. **Default for new issues.** |
| `~"workflow::Ready"`        | Ready        | Issue is fully specified and estimated, ready to be picked up in a sprint                          |
| `~"workflow::To Do"`        | To Do        | Issue is assigned to the current sprint / planned for immediate work                               |
| `~"workflow::In progress"`  | In progress  | Implementation has started (code written, MR opened, or user says so)                              |
| `~"workflow::Under review"` | Under review | MR is in code review                                                                               |
| `~"workflow::To deploy"`    | To deploy    | Merged, waiting for production deployment                                                          |

### Auto-detection rules (applied in order, first match wins)

1. **User explicitly requests a column** → use that column
2. **MR already exists or user says work has started** → `~"workflow::In progress"`
3. **Issue is well-defined with clear steps, weight, and acceptance criteria** → `~"workflow::Ready"`
4. **Otherwise** → `~"workflow::Refinement"` (safe default — issue appears on board in the refinement pipeline)

### Transitioning workflow labels

Use the `workflow_transition` script (exact label required):
```bash
pysae-ai-tools glab workflow-transition <ISSUE_IID> "<LABEL>"
```
Valid labels: `workflow::Refinement`, `workflow::Ready`, `workflow::To Do`, `workflow::In progress`, `workflow::Under review`, `workflow::To deploy`. Aliases `Refinement` / `Ready` are still accepted by the command.

## Special labels

| Label        | Usage                                                |
|--------------|------------------------------------------------------|
| `~Support`   | Linked to a Monday support ticket                    |
| `~augmented` | AI-assisted development (Claude Code, Copilot, etc.) |
| `~ANNULE`    | Issue cancelled / no longer relevant                 |

## Release-review labels

Applied by `/code-review-pre-release` to every ticket it spawns, so a release audit is fully traceable.

| Label                  | Usage                                                                                 |
|------------------------|---------------------------------------------------------------------------------------|
| `~"review::release"`   | Finding raised during a pre-release review. Group label on `pysae` (already created). |
| `~"version::vX.Y.Z"`   | Target release version of the finding (e.g. `version::v1.4.0`). One scoped label per release; created on the fly at the group level by `/code-review-pre-release` when missing. |

## Quick actions format

Generate at the end of every ticket:

```
/label ~<domain> ~<type> ~<priority> ~<board_column>
# <domain>: API, OP, DRIVER, EDITOR, INFO, INFRA, Screen, Website
# <type>: type::bug, type::feature, type::technical, type::refactoring
# <priority>: priority::P1, priority::P2, priority::P3
# <board_column>: "workflow::Refinement", "workflow::Ready", "workflow::To Do", "workflow::In progress"
/weight <fibonacci_number>
```

> **Note:** Do NOT use `/assign @me` in the description — it is not processed by the GitLab API. Use the `--assignee` flag on `glab issue create` instead.

The `<board_column>` is MANDATORY — use the auto-detected column label (e.g. `~"workflow::Refinement"`, `~"workflow::Ready"`, `~"workflow::To Do"`, `~"workflow::In progress"`).

Additional quick actions (when applicable):
- `/milestone %"milestone-name"`

**Epic attachment**: use `pysae-ai-tools glab epic-attach --epic EPIC_IID --issue PROJECT#IID` after issue creation. Do NOT use `/parent_epic` (unreliable) or `--epic` flag (project-level only).
