linear-write

name	linear-write
description	Create or rewrite Linear issues using the agent-ready card template. Use when asked to create/rewrite a Linear issue, write a spike, post an investigation-finding comment on an issue, or clean up an issue from a URL/ID.

Linear Write Skill

Create new Linear issues, or rewrite existing ones, following an agent-ready card template. The goal: produce specifications precise enough for an autonomous agent to execute on the first pass, with verifiable acceptance criteria, explicit scope, and tight risk tiering.

Tooling: MCP first, CLI fallback

Always prefer the Linear MCP tools. Fall back to the linear CLI only when MCP is unavailable or the task needs something MCP cannot do.

Action	Preferred (MCP)	Fallback (CLI)
Fetch an issue	mcp__claude_ai_Linear__get_issue	linear issue view <ID>
Create an issue	mcp__claude_ai_Linear__save_issue	linear issue create ...
Update an issue	mcp__claude_ai_Linear__save_issue (with id)	linear issue update <ID> ...
List teams	mcp__claude_ai_Linear__list_teams	linear team list
List projects	mcp__claude_ai_Linear__list_projects	linear project list
List labels	mcp__claude_ai_Linear__list_issue_labels	(CLI: not always available)
List users	mcp__claude_ai_Linear__list_users	n/a

When passing markdown to MCP tools, send real newlines, not literal \n escape sequences.

CLI install, auth, create/spike examples, and flags: see references/cli.md.

The Core Principle

You are writing a contract, not a conversation starter. Every ambiguity is a coin flip the agent will make without telling you. A card that is good enough for an agent is excellent for a human.

Writing style

Rules apply to issue bodies, comments, and spikes alike:

• No em dashes; use semicolons, commas, or prepositions instead.
• Australian spelling.
• Backticks for code identifiers, filenames, config keys, and CLI commands; preserve on-disk casing (CLAUDE.md, package-lock.json, npm typecheck).
• Plain, concrete language over institutional terms ('the arrangement' not 'the program design').
• Don't add wrap-up, summary, or evaluative closing sentences; stop when the facts are stated.
• Single quotes for scare quotes and emphasis ('in theory'), not italics.
• Lead with the finding or action, not validation or framing.
• Cite sources APA/Harvard style: a short hyperlinked label in parentheses after the referenced statement, e.g. data stops flowing once a site is migrated ([Playbook](https://...)). One-word labels only; hyperlink the label, not surrounding prose. Don't drop raw URLs inline or use numbered footnotes like [1] (Linear escapes the brackets).

The Agent-Ready Card Template

Every issue you create or rewrite MUST follow this structure:

## Summary

[One sentence: what this card accomplishes and why]

## Acceptance criteria

- [ ] [Specific, testable criterion 1]
- [ ] [Specific, testable criterion 2]

## Scope

### In scope

- [Specific change 1]

### Out of scope

- [Thing that might look related but must not be touched]

## Implementation guidance

- The relevant entry point is most likely `ClassName.methodName` ([GitHub](https://github.com/org/repo/blob/main/src/path/file.ts#L42)), which currently does:

  ```typescript
  // 👇 reproduce the problematic block so the edit site is unambiguous
  [short snippet of the referenced code, with 👇/👈 markers on the line(s) to change]
  ```

- Alternative: follow the pattern in `OtherService.method` ([GitHub](https://github.com/org/repo/blob/main/src/other.ts#L15)), or use the existing utility at `src/utils/helper.ts`
- Constraints: [any binding context the agent must respect, e.g. 'do not introduce a new dependency', 'must run inside the existing transaction']
- When uncertain: stop and explain the ambiguity, or propose a short plan rather than guessing

## Verification

- [ ] `npm typecheck` passes with zero errors
- [ ] `npm lint` passes with zero warnings
- [ ] `npm test -- --filter=<area>` is green
- [ ] `git diff` shows changes only in `src/<scope>/` and `tests/<scope>/`

## Risk tier

[Low / Medium / High] - [One sentence justification]

## Due diligence

Run the [change due diligence checklist](https://app.notion.com/p/meandu/Ctrl-alt-delight-Change-Due-Diligence-Checklist-3803c6719946810f8b7edcb94b875130) before shipping. Universal gates:

- [ ] We know how this functionality is currently used: all the ways, not just the one in the ticket; how often and by whom
- [ ] Blast radius assessed: downstream features, venues, and integrations that could be affected are listed
- [ ] Behind a feature flag where there's meaningful risk, off by default and verified; an emergency rollback path exists and has been tested

Add the conditional gates that apply (see source): existing DB data checked against a new validation or schema (scope a migration if it fails); checkout, cart, or payment changes move slowly; POS or integration plans reviewed by a custodian before code is written; schema changes staged as a backward-compatible two-step; AI-generated root cause treated as a hypothesis until confirmed.

## Files likely involved

- `src/[module]/[file].ts`

Why each section matters

• Acceptance criteria must be programmatically verifiable. If "done" requires a human judgment call, the card is not agent-ready. Replace "improve error handling" with "OAuth callback handler passes the three test cases in tests/auth/oauth_callback.test.ts".
• Out of scope prevents agent wandering. Agents are eager to "improve" adjacent code. Name what must not be touched, even when it looks related.
• Implementation guidance is the section that most often decides whether a card runs on the first pass. See the rules below.

Writing the implementation guidance section

Research the codebase as part of drafting; don't wait to be asked. Locate the primary entry point, read the surrounding pattern the agent must match, find at least one alternative or reference pattern elsewhere in the repo, and note binding constraints (transactions, feature flags, dependency boundaries, utilities to reuse). In a large or unfamiliar repo, fan this out to parallel Explore subagents (entry point, reference patterns, call sites for the 'how is it used' gate) and carry forward only their conclusions; the main thread stays clean for drafting, and real call-site evidence beats the ticket's claim of how something is used. If you have no repo access, say so in the draft and flag the section as best-effort.

Structure notes beyond the template:

• Frame the entry point as the 'culprit' or 'entry point', not a prescription. Default to reproducing the referenced code as a fenced snippet; skip only when it is >~10 lines or purely structural.
• Label ordered alternatives as 'attempt 1', 'attempt 2'.
• End with the one-line 'when uncertain, stop and surface ambiguity' instruction.

Formatting rules

• Symbol links follow APA/Harvard-style citation: `Class.method` ([GitHub](https://github.com/org/repo/blob/main/path/to/file.ext#L123)). Symbol in backticks, then a parenthetical [GitHub] label hyperlinked to the exact line. Use #L123-L145 for ranges. Don't wrap the backticked symbol inside the link text.
• Backtick all code identifiers, filenames, config keys, and CLI commands; preserve on-disk casing.
• Use fenced code blocks tagged by language (typescript, python, ```sql).
• Mark edit sites inside snippets with emoji comment arrows:
  • // 👇 ... on the line above when the target line is long.
  • // 👈 ... as a trailing inline comment when the target line is short.
  • Choose one per site; don't stack both. The comment names the edit (e.g. // 👈 missing tax recalc here), not the code.
• One real code snippet outperforms three paragraphs of prose. If you find yourself writing a paragraph, link to an example file instead.
• The heading is ## Implementation guidance (sentence case, lowercase g).

Risk tier reference

Tier	Examples	Review expectation
Low	UI copy, config, test coverage, docs	Auto-merge when gates pass
Medium	New endpoint, single-module refactor	One human reviewer
High	Auth, payments, data migrations	Two humans incl. security
Do not delegate	Architecture, novel algorithms, PII handling	Human writes, agent assists

Due diligence: understand first, then change

The change due diligence checklist is a confidence check, not just a box in the card. Work it while researching every non-spike issue (bug, security fix, or feature); its sections 1-4 feed the Scope, blast radius, and Risk tier you are drafting.

• The core gate (how is it used). If you cannot confidently answer how the functionality is currently used (all the ways, how often, by whom), do not draft a direct-change card. Propose telemetry-first two-phase work (add telemetry and monitors, gather data, then patch) or a spike, and say so explicitly in the draft.
• Surface, don't bury. If working the checklist turns up a risk or unknown (existing DB data that fails a new validation, a checkout-adjacent surface, a vendor-dependent behaviour), name it in the draft and fold the relevant gate into the Due diligence section rather than leaving it implicit.
• Time pressure. Don't quietly skip steps. Escalate to Shawn or Paul; whoever approves moving faster owns that risk. Note any skipped gate in the card rather than omitting it silently.

The Complexity / Ambiguity matrix

	Low ambiguity	High ambiguity
Low complexity	Automate immediately. First wins: config, copy, tests, simple CRUD.	Needs a spike first. Agent will guess wrong.
High complexity	Good candidate if broken into sub-tasks.	Human-driven. Architecture, novel integrations.

If a card lands in "high ambiguity", propose a spike instead of trying to write it as an executable card.

Workflow

Applies to both creating and rewriting. Steps flagged [rewrite] only apply when rewriting an existing issue.

1. [rewrite] Fetch and read. Extract the Linear issue ID (CAD-1295 or a linear.app URL), fetch via mcp__claude_ai_Linear__get_issue, and identify the core goal, listed items, open questions from the original author, and any scope/exclusion context.
2. Clarify before drafting. Batch the metadata lookups (teams, projects, labels, users) as parallel MCP calls rather than serially, then ask the questions needed to fill every section of the template. Common gaps: team/project/labels/assignee, scope boundaries, acceptance criteria, verification commands, risk tier and justification, sub-issue grouping, and (on rewrites) answers to the original author's open questions.
3. Research the codebase to fill in implementation guidance. Default to doing this whenever you have repo access (current working directory, a repo the user has opened, or GitHub search); do not wait for the user to prompt you. Follow the research checklist above. If you have no repo access, state that explicitly and mark the section best-effort.
   • For non-spike cards, work the change due diligence checklist in the same pass (see 'Due diligence: understand first, then change'). Fill the Due diligence section with the universal gates plus any conditional gate the research surfaced. If the core 'how is it used' gate can't be answered, propose telemetry-first two-phase work or a spike instead of a direct-change card.
4. Draft the full issue using the template, then run the cold-read test before presenting: fork a subagent given ONLY the card text (no conversation context) and ask it to state its implementation plan and list every assumption it had to make. Each assumption is a coin flip the card failed to pin; fix those gaps. Present the draft to the user and wait for approval before writing to Linear.
5. Create or update the issue via mcp__claude_ai_Linear__save_issue (pass the existing id on a rewrite) or, as fallback, linear issue create ... / linear issue update <ID> ....
6. Return the URL and identifier (e.g. CAD-1234).
7. Create sub-issues if requested. Each follows the same template, references the parent, and uses the same team/project/labels.

[rewrite] Preserving original content

When rewriting, always preserve the original description in a collapsed section at the bottom, and add a Q&A section if the original had open questions or clarifying questions were answered during the rewrite:

+++ # Original description (pre-YYYY-MM-DD)

[original description verbatim]

+++

## Q&A

**Q (original author):** [question from original description]
**A:** [answer determined during rewrite]

Spike Issues

A spike is a time-boxed investigation, used when ambiguity is too high to write an executable card. Ask how many days the spike should be.

Title format. Prefix the title with the duration in brackets: [2 day spike] Title, [½ day spike] Title (use the ½ character), [1 day spike] Title. Always apply the spike label (-l "spike" via CLI, or include it in the labels list via MCP).

Description template. Pick Spike Questions (investigating an unknown) or Action Items (enumerating known work):

# Spike Questions to Address  ← use for exploratory spikes

- What is the size and scale of the problem?
- What is the root cause?
- What are the potential solutions or fixes?
- Is it worth fixing? (effort vs impact)

# Action Items  ← use for enumeration spikes

- Review scope and identify specific items that need work
- Note constraints or special considerations for each item
- Compile list of tasks; have team/PM review and prioritise
- Create Linear issues for approved work

# Possible Outcomes

- Additional spike required; if further investigation is needed
- Close as won't do; if effort outweighs benefit
- Create resolution issue / sub-tasks for each item; if we decide to proceed
- Fix issue; if solution is simple and time allows

Use bullets, not numbered lists. Linear's renderer silently drops items after the first in multi-item numbered lists saved via MCP.

The spike card itself doesn't carry the full due diligence gates; the investigation is what informs them. When a spike resolves into work, note under Possible Outcomes that any resolution issue or sub-task runs the change due diligence checklist, e.g. add Create resolution issue / sub-tasks (each runs the change due diligence checklist) to the outcomes list.

Comments

Comments follow the same writing-style rules as issue bodies. Investigation findings, audit results, and out-of-band updates belong in comments; the description is the contract, the comment is the journal.

Investigation finding template (for comments documenting an audit, CVE triage, 'not reproducible' outcome, etc.):

**[One-line finding in bold.]**

[Short paragraph explaining the finding with the key file/line link.]

Verified by:

- [Specific check 1, with the exact command or URL]
- [Specific check 2]

[Optional: short paragraph on related-but-unaffected items you considered.]

[Recommendation, e.g. 'Closing as cancelled' or 'Reopening as P2'.]

The verification list is load-bearing. Each bullet should be a check the reader can re-run: a git log -S command, a clickable GitHub code search URL, a specific file path with line numbers. No vague 'I checked the codebase' prose.

Issue Relationships

Relationship	MCP	CLI	How to set
Parent	Yes (save_issue with parentId)	Yes (-p <ISSUE>)	Set during creation, or update later
Sub-issue	Automatic	Automatic	Create with parent set
Blocked by	Limited	Not supported	Set manually in Linear web UI
Depends on	Limited	Not supported	Set manually in Linear web UI

Tips and Gotchas

• Escaping @ mentions. Linear parses @ as a mention trigger and shells may interpret it as command substitution. Wrap package names in backticks (`@mr-yum/foo`) inside descriptions; wrap shell args in single quotes; or use --description-file to bypass shell quoting entirely.
• Team identifiers are usually uppercase (CAD, ENG, PROD, CUSM).
• Numbered lists get truncated. Multi-item 1. 2. 3. lists saved via MCP often drop everything after the first item silently. Use bulleted lists unless order is semantically required, and verify with get_issue if you do use numbers.
• Bulleted lists can also collapse. Bullets that share a line break without a blank line between them sometimes drop everything after the first item too, especially under headings like ### Out of scope near a fenced code block. After saving, fetch the issue back with get_issue and check that every bullet survived; if a section was clipped, re-save with a blank line between bullets and the items will stick.
• More detail isn't always better. A 500-word card with contradictory instructions is worse than a 100-word card with clear acceptance criteria.

Guidelines

• If acceptance criteria sound testable but are subjective ("clean up the error handling", "improve" something), push back and rewrite them as something verifiable.
• Risk tier should reflect the actual change, not the importance of the feature.
• When listing handlers, endpoints, or items, prefer grouping by module or domain over enumerating individually.