Module 2: The Issue Lifecycle
Master the 7-state lifecycle and label system that powers all L3 work.
Estimated time: 15 minutes
The 7 States
Every issue in the L3 ecosystem follows a strict lifecycle. No skipping states — except for P1 emergencies.
Backlog → Triaged → To Do → In Progress → In Review → Deployed in Dev → Done| State | What Happens | Time Limit |
|---|---|---|
| Backlog | Issue just landed. Claude auto-triage picks it up within seconds. | Max 24 hours |
| Triaged | Claude has processed it. Waits for the Thursday weekly review where Ops + Tech Lead decide what enters the next cycle. | Issues not accepted within 7 days are auto-archived Friday |
| To Do | Accepted into the cycle. Assigned to an engineer. | Engineer must pick it up within 48 hours |
| In Progress | Engineer is actively working. A GitHub branch must be linked. | — |
| In Review | PR is open, review requested. PR must reference Fixes #N. | Reviewers have 48 hours |
| Deployed in Dev | Code merged and deployed to the dev environment. This is a mandatory gate — you cannot skip it. QA or the engineer validates in dev before promoting to production. | — |
| Done | Deployed to production and verified live. This is the terminal state. | — |
Key Rule: Merged ≠ Done
A common mistake: marking an issue as Done when the PR is merged. Merged is not Done. The change must be deployed to production and confirmed working. That's why "Deployed in Dev" exists as a mandatory gate.
P1 Fast-Track
For urgent issues (production down, data loss, critical security), issues skip Triaged and To Do and go directly to In Progress. They still must pass through In Review and Deployed in Dev. Ops gets pinged in Slack immediately.
P1 criteria:
- Active production outage
- Data corruption in progress
- Critical security vulnerability being exploited
- Customer-facing outage with revenue/SLA impact
The Label System
Labels are how the platform classifies and routes work. There are four categories:
Type Labels
| Label | When to Use |
|---|---|
Bug | Defect in existing functionality |
Feature | New capability or enhancement |
Improvement | Enhancement to existing functionality |
Spike | Time-boxed investigation, no deliverable code expected |
Platform Labels
| Label | Scope |
|---|---|
FE | Frontend — web client, mobile, UI, CSS, layout |
BE | Backend — server, API, database, infrastructure |
Design | UI/UX, visual design, design systems |
Important rule: If a bug shows wrong, missing, or duplicate data — even if it appears in the UI — classify it as BE. Layout, styling, interactions, and responsiveness are FE. When in doubt between FE and BE, lean BE.
Complexity Labels
Set automatically by the ingestion service's Claude classification:
| Label | Definition |
|---|---|
complexity:low | Single file, mechanical change (rename, config, style tweak, copy fix) |
complexity:medium | Multiple files, clear scope but requires investigation (new endpoint, multi-file bug fix) |
complexity:high | Unclear scope, requires design decisions, touches architecture, multiple systems |
AI Workflow Labels
These are the most important labels for understanding automation:
| Label | Meaning | What Happens |
|---|---|---|
needs-review | Claude's classification confidence was below 0.7. A human must review before any work begins. | Blocks Claude Code automation |
ai-plan | Human has decided Claude should create an implementation plan (no code). | Triggers claude-code-plan.yml → creates a draft PR with a plan document |
ai-triaged | Human has decided Claude should fully implement this issue. | Triggers claude-code.yml → Claude implements and opens a PR |
human-only | Requires human judgment. Claude should not auto-triage or implement. | No automation triggers |
Priority (Not a Label)
Priority uses Linear's built-in Priority field, not labels:
- Urgent (P1): Production down, data loss, critical security
- High (P2): Blocks work, client regression, significant friction
- Medium (P3): Planned work, normal priority (default)
- Low (P4): Nice-to-have, future consideration