Topic: ADR template in Linear

ADR Template in Linear — Documents, Custom Properties, and the Graduated Handoff

Q: Can Linear Documents replace git-based ADRs long-term?

No — for two structural reasons. First, ADRs derive their authority from being immutable once Accepted: a Markdown file committed to git cannot be silently edited without a commit trail. Linear Documents can be edited without audit trail by anyone with edit access to the Document, undermining the immutability guarantee. Second, ADRs need to survive company tool migrations. Many teams that adopted Confluence for documentation have had to migrate those decisions somewhere else; Markdown files in a code repository outlive every project management tool. Linear Documents should be used for the drafting and review phase (when iteration is expected), then graduated to a committed Markdown file once the decision is Accepted. The Linear Document becomes a record of the deliberation; the committed file is the canonical ADR.

Q: What Linear custom properties are most useful for ADR tracking?

The most useful custom properties on a Linear Document for ADR tracking are: Status (select field with values Proposed / Under Review / Accepted / Superseded / Deprecated), Decider (member field — the engineer or engineering manager who made the final call, not the author of the Document), Date decided (date field — when the decision was formalized, not when the Document was created), and Supersedes (text field — the ADR number of the decision this one replaces, if any). Avoid adding too many properties at the start: a 3-person team needs Status and Decider; the other fields add value at 10+ people when the roster of people asking 'wait, who decided this?' expands. Linear lets you add properties to a Document template, so the template enforces consistent field presence without requiring every team member to remember which fields matter.

Q: How do you link Linear ADR Documents to the issues they affect?

Linear has a native Relations feature for Documents: open a Document → click the Relations icon in the sidebar → link to one or more Issues or Projects. The linked Issue then shows the Document in its own sidebar under Related Documents. The recommended linking pattern for ADRs: link the ADR Document to (1) the Initiative or Project it governs (the high-level context), and (2) any Issue that triggered the decision — the bug or feature request that forced the architecture call. Do not link ADR Documents to every Issue in the affected area — the signal-to-noise ratio collapses. Use a naming convention in the Document title (e.g., 'ADR-042: Switch from REST to GraphQL') so engineers can reference the ADR number in Issue comments without navigating to the Document. When the ADR graduates to a Markdown file in the repository, add the Linear Document URL to the ADR's Context section as the 'Deliberation record' so the link is preserved even after Linear is replaced.

Q: Does Linear's data export include the full text of Documents?

Partially. Linear's built-in export (Settings → Export → CSV) exports Issues with their descriptions, labels, and custom fields — but Documents are not included in the CSV export. The Linear API does expose Documents via the document query in the GraphQL API, including title, content (as a document object in a structured format), and custom properties. The content field uses Linear's internal document format (not Markdown), which requires conversion. As of 2026 Linear does not offer a one-click Document export to Markdown. If your ADRs are in Linear Documents and you need to migrate them, the path is: Linear GraphQL API → extract content field → convert to Markdown manually or via a script. This is a real migration friction, which is why the graduated handoff pattern (draft in Linear, commit to Markdown in git) is recommended: the Markdown file is always the source of truth, and the Linear Document is a transient drafting artifact that can be safely archived or deleted once the Markdown file is committed.

Many engineering teams that use Linear for project management want their architecture decision records in the same tool — close to the issues they govern, searchable alongside epics, visible in the context where decisions get acted on. Linear Documents provide the right drafting surface. But Linear is not the right archive for ADRs long-term. This page explains the graduated handoff pattern that uses both tools for what each does best.

TL;DR

Use Linear Documents to draft and review ADRs (the collaborative, mutable phase), then graduate each Accepted ADR to a Markdown file committed in the code repository (the immutable archive). Set up a Decision Documents workspace in Linear with custom properties for Status, Decider, and Date decided. Link each ADR Document to the relevant Issue or Project. Once the decision is Accepted, commit the Markdown file and mark the Linear Document as archived — the Document becomes the deliberation record, the Markdown file is the canonical ADR.

Why engineers want ADRs in Linear

The appeal is proximity. A decision to switch from REST to GraphQL is not an abstract artifact — it was caused by a specific set of Issues and it affects a specific Project. Engineers who discover it via a Linear Issue shouldn't have to context-switch to a different tool or navigate a git repository to find the rationale. Linear Documents sit inside the same workspace as the Issues, visible in the sidebar of the Projects they govern, searchable from the same command palette.

Linear also provides what plain Markdown files in a repository lack: a collaborative drafting environment. Multiple engineers can edit a Linear Document simultaneously, leave comments on specific paragraphs, and iterate on the Decision section without making a git commit for every revision. The review cycle for an ADR — where the lead engineer proposes the decision, others push back on the Alternatives section, the CTO adds a note to Consequences — happens more naturally in a Document than in a pull request.

The third appeal is integration. Linear Cycles and Projects track what the team is building. An ADR Document linked to the Cycle that will implement the decision keeps the 'why' one click away from the 'what' and 'when'. Engineers who join mid-cycle can read the ADR without leaving the tool they have open.

Setting up Decision Documents in Linear

Linear organizes Documents within a Team or Workspace. The recommended structure:

Create a Documents folder called Architecture Decisions in the relevant Team (or in a cross-team Workspace folder if decisions span multiple teams). Do not use a Project for this — Projects have a lifecycle that ends when the project does; ADR Documents should persist beyond any single Project.
Create a Document template with the ADR structure pre-filled. Linear Document templates appear in the New Document menu and enforce a consistent starting point without requiring engineers to remember the ADR format.
Add custom properties to Document templates to track ADR-specific metadata across the folder without embedding metadata in the body text.

The Linear ADR Document template

Copy this into your Linear Document template. The section order matches the Nygard template so it is compatible with the Nygard ADR format when you graduate to Markdown:

# ADR-[NUMBER]: [Title — name the decision, not the problem]

## Status
Proposed | Under Review | Accepted | Superseded | Deprecated

## Context
[Two to four sentences. What situation forced this decision? What constraints exist?
What would happen if we did nothing? Do not include the decision itself here.]

## Decision
[One active-voice sentence naming what was chosen. "We will use X." Not "X was chosen" or "We should consider X."]

## Consequences
[Bulleted list. Include at least one genuine downside — an ADR with only positive consequences is a press release.
Separate positive consequences (marked +) from negative ones (marked –) from neutral ones (marked ~).]

### Positive
- + [something that improves]

### Negative (trade-offs)
- – [something that gets worse or becomes harder]

### Neutral
- ~ [something that changes but is neither better nor worse]

## Alternatives considered
[For each alternative you rejected, one sentence on why. Prevents re-litigating closed decisions.]

| Option | Why rejected |
|---|---|
| [Option A] | [one-sentence rejection rationale] |

## Stakeholders
[Who was consulted before this decision was made? Relevant for decisions that affect other teams.]

## Deliberation record
[Link to the Linear Issue or discussion thread that triggered this decision. Added at graduation time.]

Custom properties to add to the template

Property name	Type	Values / notes	When to use
Status	Select	Proposed / Under Review / Accepted / Superseded / Deprecated	Always. This is the field that drives dashboard filtering.
Decider	Member	Single member — the engineer who made the final call	Teams of 5+. Prevents the "who owns this?" question during oncall handoff.
Date decided	Date	When the Status moved to Accepted — not when the Document was created	Always. Gap between created and decided reveals how long decisions take to finalize.
Supersedes	Text	ADR number of the decision this one replaces (e.g., "ADR-017")	Only when this ADR supersedes a prior decision. Keep it a text field — the CI check on the Markdown file will enforce the actual file pointer.
Repo file	URL	Direct link to the committed Markdown ADR file in GitHub/GitLab	Added at graduation time. Turns the Linear Document into a pointer to the canonical file.

Linking ADR Documents to Issues and Projects

Linear's Relations feature (Document sidebar → Relations icon) lets you link a Document to Issues, Projects, and other Documents. For ADRs the most useful links are:

Link to the triggering Issue. The bug or feature request that forced the architecture decision. When engineers open that Issue six months later, they see the ADR immediately — no repository navigation required.
Link to the governing Project or Initiative. The high-level work stream the ADR applies to. Engineers scoping a new Cycle in the same area will encounter the ADR as they plan.
Do not link to every affected Issue. If an ADR about GraphQL migration is linked to 47 Issues in the sprint, the signal collapses into noise. Link to the origin Issue and the governing Initiative; let engineers discover the ADR via search for everything else.

In Issue descriptions and comments, reference ADRs by number: See ADR-042 (Linear: [link]) for the rationale. Include both the number (for searchability in the Markdown file) and the Linear link (for engineers in the Linear context). Once the ADR is graduated to Markdown, update the comment to point at the repository file instead — the Linear Document URL should be treated as a temporary review link, not a permanent citation.

The graduated handoff: from Linear draft to committed Markdown

This is the core of the Linear ADR pattern and the reason it works where a pure-Linear approach fails. The lifecycle has three phases:

Draft in Linear. Create the Document from the template. Engineers iterate collaboratively — editing the Consequences section, arguing in comments about the Alternatives table, tagging the Decider. Status is Proposed or Under Review. The Document is mutable and expected to change.
Accept and graduate. When the team reaches consensus, mark the Linear Document Status as Accepted. Copy the Document content to a Markdown file using the Nygard filename convention (NNNN-title-in-kebab-case.md). Commit the Markdown file to the /doc/decisions/ directory via a pull request. The PR description links back to the Linear Document as the deliberation record. Merge the PR.
Archive the Linear Document. Update the Document's Repo file property with the direct link to the committed Markdown file in GitHub/GitLab. Set the Document to read-only (comment-only mode, or simply by team convention) and add a notice at the top: This Document has graduated to [ADR-042 in the repository]. This page is a deliberation record — it is not the canonical ADR. Do not edit it.

The graduated Markdown file is now the canonical ADR. It is subject to the ADR review checklist, the GitHub Action CI validation, and the immutability guarantee that ADRs derive their authority from. The Linear Document is preserved as the deliberation record — useful for future engineers who want to understand the discussion, not just the decision.

The Linear export gap

Understanding what Linear does and does not export matters for long-term ADR preservation:

Item	In Linear CSV export?	Via Linear API?	Notes
Issue titles, descriptions, labels, custom fields	Yes	Yes	The core Issue data is well-covered by both paths.
Document titles	No — Documents not in CSV export	Yes — via `document` GraphQL query	Title is available via API; not in the settings CSV export.
Document body content	No	Yes — as structured document object, not Markdown	Linear's internal format requires conversion. No one-click Markdown export as of 2026.
Document custom properties	No	Yes — via API alongside Document object	Status, Decider, Date decided are all API-readable.
Document comments	No	Yes — via `comments` field on Document	The deliberation comments are the most valuable part for historical context — extract via API before migrating away from Linear.
Document relations (linked Issues/Projects)	No	Yes — via `relations` field	Relational graph is only queryable via API; not in any file export.

This export gap is the structural argument for the graduated handoff: if your ADRs are only in Linear Documents and your company migrates away from Linear, recovery requires a custom GraphQL extraction script, format conversion, and manual review. If your ADRs are Markdown files in git, they survive any tool migration — the repository is the source of truth and every editor reads Markdown natively.

Linear vs other tool-specific ADR storage

Tool	Best use in ADR lifecycle	Immutability guarantee	Export path	Cross-links to Issues?
Linear Documents	Drafting and review	None — editable by anyone with access	GraphQL API (body not Markdown)	Yes — native Relations feature
Git repo (Markdown files)	Canonical archive	Full — every edit is a commit with author + timestamp	Native — files are already Markdown	Via link in ADR text / PR description
Notion	Drafting and stakeholder review	None — full edit history but no immutability constraint	Markdown export available	Via relation property / mentions
Confluence	Enterprise stakeholder review and publication	None — page versioning but no immutability constraint	PDF / Word export	Via Jira issue macros
Obsidian	Personal PKM for drafting and Dataview querying	Via git sync (optional)	Native Markdown	Via wikilinks to issue URLs in notes

Why this matters for decision capture

The graduated handoff pattern solves the drafting-vs-archive problem. But it does not solve the deeper problem: decisions that were never written down in the first place. Engineers who use ChatGPT or Claude to think through architecture calls — discussing Postgres vs Redshift in a prompt session, evaluating three caching strategies with an AI assistant — rarely convert that reasoning into a Linear Document, let alone a committed ADR. The reasoning is in the chat history, not in any project management tool.

For decisions already in your AI chat history, the WhyChose extractor reads your ChatGPT or Claude export and surfaces the architecture calls inside as structured decision records — formatted in Nygard-compatible Markdown, ready to drop into /doc/decisions/ without rewriting from scratch. The extracted records can also serve as the starting point for a Linear Document: paste the extracted ADR into a new Document, tag the Decider, set the Status to Under Review, and trigger the review cycle that the original chat session skipped.

Get early access