---
name: linear-triage
description: Linear project management for a product → design → engineering team. Use whenever the user mentions Linear or an issue identifier like TEAM-123 — writing or reviewing an issue, shaping a project or writing its brief, moving an issue between statuses, auditing a board, recording a decision, or drafting a project update.
---

# Linear

Work in Linear with the `mcp__claude_ai_Linear__*` tools. Every write is
**prepare → confirm → execute**: show the exact change, wait for approval, apply,
re-read and report what landed.

- [ISSUE-WRITING.md](references/ISSUE-WRITING.md): the three issue shapes, what to cut, examples
- [PROJECT-WRITING.md](references/PROJECT-WRITING.md): project brief, milestones, decomposition, updates
- [TRIAGE.md](references/TRIAGE.md): board and issue audits
- [LABELS.md](references/LABELS.md): label taxonomy

## Where things live

| Tool | Holds |
| --- | --- |
| Notion | Strategy: OKRs, quarter plans, partner docs |
| Linear project | Brief, milestones, updates, project-wide decisions |
| Linear issue | One unit of work and the decisions about it, as comments |
| Figma / tldraw / Storybook | Design artifacts, linked from the issue. Never scope on their own |
| Slack | Pings. A decision taken there is linked into Linear within a day |

A decision is recorded at the scope it binds: one issue → a comment on it, then the
description edited if the contract changed; the whole project → a comment on the
brief, or a line in its "Decisions" document. Read existing comments before asking
a question again.

## Hierarchy

**Initiative → project → milestone → issue.**

- **Project**: several people, more than ~2 weeks, or its own status reporting.
  Needs a brief, a lead and a target date.
- **Milestone**: a stage with exit evidence and its own date, never a layer.
- **Parent issue**: one deliverable with real sub-issues.
- **Leaf issue**: 1–5 days of work one person can verify.
- One-off bugs and polish live in the team backlog with no project.

## Statuses

The assignee is the current owner. A handoff changes the assignee and gets a Slack
ping. A backwards move carries a one-line comment.

| Status | Means |
| --- | --- |
| Triage | Raw intake, evidence verbatim |
| Backlog | Labelled, prioritised, deduped |
| Shaping | Someone is writing it up |
| Ready | One objective, open questions explicit, owner knows when it's done |
| In Progress / In Review / Done | Claimed / PR open / shipped |

## Comments posted by an agent

```
**Triage note** (generated by AI)

[content]
```

## MCP gotchas

- Edit descriptions with `patch` ops; anchors must match once.
- `labels` on `save_issue` replaces the whole set; pass the full list.
- Milestones can't be deleted through the MCP: rename to "Retired, delete me".
  Re-read milestone descriptions after saving; a first save has failed to persist.
- Cancelling keeps the body; prepend the one-line reason.
- After a batch of writes, re-read and diff against what you intended.