Linear

---
name: linear
description: "ArcBox's Linear workflow. Use whenever starting a task that may have or need a tracking issue, or working with Linear at all — finding, creating, or updating issues, syncing progress, moving status, triage, or branch/PR linking. Trigger on any mention of Linear, an issue/ticket, an issue ID like ABX-123, a project, the board, or sprint/standup planning."
---

# Linear Workflow

Linear is the source of truth for what's being worked on. Keep issues in sync with reality, and treat an issue's history as shared — prefer adding over rewriting.

Resolve teams, projects, labels, statuses, and people **by name** (`list_teams`, `list_projects`, `list_issue_labels`, `list_issue_statuses`, `list_users`). Never paste raw IDs.

## Before Starting a Task

1. **Search first.** Look for an existing issue before doing the work — `list_issues(query:…)`, or filter by project/label/assignee. Don't assume there isn't one.
2. **If none exists**, don't silently create it. Ask the user the scope: which team and project, and whether it's one issue or several sub-issues. Then create it per *Creating Issues*.
3. **If one exists**, read it fully (`get_issue`, `includeRelations:true`) and bring it up to date before working:
   - Does the status reflect reality? Move it (e.g. → In Progress).
   - Is the assignee whoever is actually doing it? Fix it.
   - Is context missing — a decision, a new constraint, a related issue? Add it as a comment.

## While Working

- **Sync through comments** (`save_comment`), promptly. When you hit a blocker, change approach, or learn something that shifts scope, leave a comment — don't let the issue drift from reality, and don't bury the change by rewriting the description.
- **Move status as it changes**: In Progress when you start, In Review when a PR is open, Done when merged.

## Editing the Description

The description is the agreed spec. Once an issue is old, accepted, or has discussion, treat it as append-only:

- Prefer a **comment** over editing the description at all.
- If you must edit: wrap large removals in strikethrough (`~~…~~`) instead of deleting them; prefix any changed or added line with **`EDIT (YYYY-MM-DD):`** so the original intent stays legible.
- A fresh issue you just created, with no discussion yet, can be edited freely.

## Creating Issues

- Confirm scope (team / project / how to slice it) with the user first unless it's obvious.
- **Title**: imperative, no ID prefix (Linear adds `ABX-N`). Use a conventional-commit prefix (`fix(vmm):`, `feat(sandbox):`) when the issue maps to a code change; otherwise a plain descriptive title.
- **Labels**: exactly one `type:` label plus one or more `area:` labels (resolve names with `list_issue_labels(team)`). Use only the parented `type:`/`area:` system — ignore legacy duplicates like flat `networking` / `Bug` or migrated `area: ci`. Apply only labels that already exist; **never create a label** — if a needed one is missing, ask the user.
- **Priority** `1` Urgent … `4` Low. **Assignee** by name/email/`"me"`. Set `project` and the current `cycle` for active work; add an `estimate` only when planning a cycle.
- Break large work into sub-issues with `parentId` rather than one giant issue.
- **Description**: Markdown with literal newlines. Bug → Problem / Root cause / Fix; task → Goal / Tasks / Acceptance. Reference code as `path:line`.

## Status & Branch Linking

- Lifecycle: Backlog → Todo → In Progress → In Review → Done (plus Canceled, Duplicate). Resolve names with `list_issue_statuses(team)`; teams may differ.
- Use the issue's `gitBranchName` (from `get_issue`) as the git branch — Linear's GitHub integration then auto-links the branch and PR and advances status.

## Tooling

`save_issue` creates (omit `id`) and updates (pass `id`). `get_issue(includeRelations:true)` for full context. `list_comments` / `save_comment` for the discussion log. Pass team/project/labels/state/assignee by name.