Linear formatting

Purpose: Standardizes how Linear issue descriptions and comments are structured, ensuring consistency, scannability, and correct use of Linear-native formatting features.

How to format Linear issue descriptions and comments for consistency and scannability.

Comment format

Every Linear comment follows this structure:

1. Heading — #### Comment Title
2. Summary — Blockquote numbered list (always visible, scannable)
3. Details — Blockquote-indented collapsible > +++ sections (collapsed by default, visually nested under summary)

Syntax

#### Comment Title

> 1. First key point
> 2. Second key point
> 3. Third key point
>
> +++ #### *Detail Section Title*
> Detailed content here. Can include lists, tables, code blocks.
> +++
>
> +++ #### *Another Detail Section*
> More details.
> +++

Rules

1. Summary is a blockquote numbered list — Always visible, never collapsible
2. Each summary point is one sentence — Scannable in 5 seconds
3. Details go in blockquote-indented collapsible sections — > +++ #### *Title* / > +++, collapsed by default, visually nested under the summary. Collapsible headings use h4 italic (#### *Title*)
4. Use numbered lists inside collapsible sections — For consistency
5. Tables are acceptable — Inside collapsible sections
6. @Ameet mentions go outside collapsible sections — Visible without expanding
7. The +++ syntax is Linear-native — Do not use HTML <details> tags (they don't render in Linear)
8. Collapsible sections inside blockquotes (> +++) — Creates visual indentation; always use this pattern, never bare +++
9. No expanded-by-default collapsibles via API — Expanded state is only settable through the Linear UI (ProseMirror bodyData). The MCP body field always renders collapsibles as collapsed

Comment types

Type	Heading Pattern	Summary Focus
Research/Findings	#### Research Findings: {topic}	Key conclusions, scope, review stats
Checkpoint	#### @Ameet — Input Needed	What's ready, what's needed, options
Implementation	#### Implementation Summary	Files changed, key decisions, verification
Review Synthesis	#### Review Complete	Reviewer count, findings fixed/rejected/tracked, commit refs
Done	#### Done	PR#, files changed, preview URLs
Design Deliberation	#### Plan: {title}	Implementation steps, team consensus, confidence score

Design deliberation comments

When a team deliberates on a design decision, capture the reasoning in a collapsible section so it's traceable later. Include which options were considered, why alternatives were rejected, and a confidence score.

#### Plan: {title}

> 1. What we're doing
> 2. Key implementation steps
> 3. Why this approach
>
> +++ #### *Design Deliberation ({N}% confidence)*
> **Team:** {reviewer names}
> **Convergence:** {X}/{Y} on {chosen option}
>
> **Options considered:**
> 1. **{Option A}: {name}** — {chosen/rejected}. {Reasoning}.
> 2. **{Option B}: {name}** — {chosen/rejected}. {Reasoning}.
> 3. **{Option C}: {name}** — {chosen/rejected}. {Reasoning}.
>
> **Confidence notes:** {Why confidence is at this level — depth of deliberation, strength of evidence, unresolved concerns.}
> +++

Rules:

1. Confidence score reflects deliberation depth — Not just vote count; fast unanimous convergence with shallow debate scores lower than hard-fought consensus
2. Always list rejected options with concrete reasons — "No frontmatter support" beats "not preferred"
3. Include the team composition — So you know whose perspectives informed the decision

Comment templates

Templates for each milestone comment type. Use these exact formats for consistency.

Implementation summary

Posted when implementation is complete (before review). Captures what was done, key decisions made during implementation, and any data migrations performed.

#### Implementation Summary

> 1. Branch: `type/issue-id-slug`
> 2. [count] files changed
> 3. Verification: passed (type-check, lint, build)
>
> +++ #### *What Changed*
> 1. `path/to/file.md` — what was changed and why
> 2. `path/to/other.ts` — what was changed and why
> +++
>
> +++ #### *Decisions*
> | Decision | Choice | Rationale |
> |----------|--------|-----------|
> | Short decision name | What was chosen | Why |
> +++
>
> +++ #### *Data Migration*
> (Include only if data was moved, transformed, or backfilled)
> 1. What was migrated, from where to where
> 2. How many records/files affected
> +++

Notes:

• Decisions section is required — Captures choices made during implementation that aren't in the spec
• Data Migration section is optional — Only include when data was actually moved
• Keep file descriptions to one line each — Link to the PR for full diff

Review synthesis

#### Review Complete

> 1. X reviewers: [list names]
> 2. Y findings fixed (A auto-fixed New Findings: [title1, title2]), Z rejected, W tracked
> 3. All changes in commit `abc1234`
>
> +++ #### *Fixed (Y items)*
> - [x] SQL injection in handler — parameterized query *(Security Auditor)*
> - [x] Missing RLS policy — org_id RLS added *(Security Auditor)*
> - [x] N+1 query — batch fetch *(Technical Critic)*
> - [x] Updated security standard to match new auth flow *(Standards Guardian)*
> - [x] Add hooks to inheritance checklist — added line *(Framework)* (New Findings)
> +++
>
> +++ #### *Rejected (Z items)*
> - "Finding title" — Rationale for rejection *(Reviewer Name)*
> +++
>
> +++ #### *Tracked in existing scope (W items)*
> - Finding — where it's tracked (V1.1 scope, RAJ-XXX, etc.)
> +++

> **New Findings** (check to create Framework issues)
> - [ ] Add parallel execution decision tree to sdlc.md — *(Framework)*

Checkpoint

#### @Ameet — Input Needed

> 1. Context: what phase, what was produced
> 2. What's needed from human

+++ #### *Options*
Option details here.
+++

Done summary

#### Done

> 1. PR #[number] merged
> 2. Main preview verified
> 3. [count] files changed, [count] tests added
>
> +++ #### *URLs*
> - Preview: [branch preview URL]
> - Main preview: [main preview URL]
> +++

Issue description format

Structured for scannability. No collapsible sections in descriptions — everything is visible.

When to apply: The orchestrator reformats the issue description as Step 0 of the pipeline -- before any other work begins. This turns prompt-style descriptions into structured, scannable issues. See CLAUDE.md § "Step 0: Format Issue".

Syntax

#### Summary

> 1. What this issue is about
> 2. Why it matters
> 3. Expected outcome

#### Problem  ⚫ Blocker  ·  🔴 Critical  ·  🟠 High  ·  🟡 Medium  ·  🟢 Low

> 1. 🔴  First problem item with severity
> 2. 🟠  Second problem item
> 3. 🟡  Third problem item

#### Scope

> **V1 (implement now):**
> 1. First scope item
> 2. Second scope item
>
> **V2 (deferred):**
> 1. Future scope item

#### Related Issues

> RAJ-229, RAJ-280, RAJ-281

#### Acceptance Criteria

> 1. First criterion
> 2. Second criterion

#### Phase Checklist: {Status}

> - [x] Completed item
> - [ ] Pending item

Rules

1. Use #### Heading (h4) for all sections — Consistent with comment format
2. All content in blockquotes — Creates visual indentation for scannability
3. No collapsible sections in descriptions — Everything should be visible at a glance
4. Severity uses emoji scale — ⚫ Blocker, 🔴 Critical, 🟠 High, 🟡 Medium, 🟢 Low
5. Severity legend goes in the Problem heading itself — E.g., #### Problem ⚫ Blocker · 🔴 Critical · ...
6. Each problem item is prefixed with its severity emoji — And two spaces for visual separation
7. Phase checklists use blockquote-indented checkboxes — > - [ ]
8. Related issues use bare identifiers in CSV format — E.g., RAJ-229, RAJ-280; markdown links auto-embed with full titles, which is unwanted
9. <sub>, <details>, and other HTML tags do not render in Linear — Use only markdown

Sections

Section	Required	Purpose
Summary	Yes	What and why in 1-3 points
Problem	When applicable	Categorized findings with severity
Scope	For features	What's in/out, phased if applicable
Related Issues	When applicable	Cross-references to related work
Acceptance Criteria	Yes	Definition of done for this issue
Phase Checklist	Yes (added by orchestrator)	Current pipeline phase progress

Linear platform limitations

Known formatting constraints discovered through testing:

1. <details> / <summary> HTML — Does not render. Use +++ native syntax instead
2. <sub> / <sup> HTML — Does not render. No small/superscript text available
3. Expanded-by-default collapsibles — Not possible via API. The bodyData (ProseMirror JSON) stores expanded state, but the MCP only exposes body (markdown), which always renders collapsed
4. Markdown links — [text](url) with Linear issue URLs auto-embeds with full issue title. Use bare identifiers (e.g., RAJ-229) instead for compact references
5. Bare issue identifiers — RAJ-229 is NOT auto-linked in Linear. It's just plain text. But it's still preferred over auto-embedded links for readability
6. Indented +++ — Spaces before +++ break rendering. Use > +++ (blockquote prefix) for visual indentation instead

---

Linear Formatting v2.0 — March 2026