How to Write Acceptance Criteria in Linear
Linear's fast, keyboard-driven interface makes it the favorite issue tracker for engineering-led teams. But its streamlined design can encourage lightweight issue descriptions — including skipping acceptance criteria entirely. A Linear issue without AC is an instruction to build something without a definition of done.
This guide covers how to write structured acceptance criteria inside Linear issues using markdown formatting, templates, and Linear's label and workflow features to enforce AC completeness before stories enter development.
Step-by-step guide
Open the issue and add an AC section in the description
Open your Linear issue and click into the description area. Type "## Acceptance Criteria" to create a markdown heading. Linear renders markdown in real time, so the section header appears immediately. Below the heading, use hyphens to create a markdown list. Linear supports full markdown including bold, code blocks, and checkboxes (- [ ] syntax).
Use checkbox syntax for testable criteria
Write each criterion as a checkbox: "- [ ] Given a user is logged in, When they click Archive on a project, Then the project moves to the Archived section and disappears from the Active view." The checkbox syntax creates a visual progress indicator in Linear and signals to QA which items have been verified.
Apply a "Needs AC" label to incomplete issues
In Linear Settings > Labels, create a label called "Needs AC" with a red or orange color. Apply this label to any issue that enters the Backlog without acceptance criteria. Create a Linear filter: Label is "Needs AC" AND Status is not "Done" — bookmark this as a saved view called "AC Gaps." Review this view weekly during backlog grooming.
Create an issue template with AC pre-formatted
In Linear Settings > Templates, create a Story template. Include these sections: "## Problem Statement", "## User Story (As a... I want... So that...)", "## Acceptance Criteria" with placeholder checkboxes, and "## Out of Scope." When engineers or PMs create new issues using this template, the AC section is always present.
Tag the assigned engineer in the AC comment for explicit sign-off
After writing AC, add a comment tagging the assigned engineer: "@alex — please review AC below and flag any ambiguities before pulling this into the sprint." This creates a named sign-off record in Linear's comment history. Linear's notification system ensures the engineer sees the tag even if they do not check the issue proactively.
Use Linear sub-issues for complex criteria
For issues with more than 7 acceptance criteria, consider splitting them into sub-issues. In Linear, click "+ Add sub-issue" from the parent issue. Each sub-issue represents one behavioral scenario (happy path, error state, edge case). This keeps the parent issue clean and allows individual scenarios to be tracked separately in the cycle.
Common mistakes
Leaving AC as free-form notes instead of testable statements
Notes like "make sure the pagination works correctly" are not acceptance criteria. They do not define what "correctly" means. Every criterion must be testable: "Given 50+ items exist, When the user scrolls to the bottom of the list, Then the next 25 items load without a full page refresh."
Not updating AC when requirements change
Linear makes it easy to update descriptions. When scope changes, update the checkbox list immediately and add a comment noting what changed and why. Stale AC is worse than no AC — it gives false confidence that the issue is fully specified.
Writing AC only for the happy path
Error states, empty states, and loading states are the scenarios that cause the most bugs. For every functional criterion, ask: "What happens if this fails?" Add at least one error-state criterion per issue.
Using Linear Cycles without AC-complete issues
Pulling issues into a Linear Cycle (sprint) without complete AC means the team commits to work that is not fully defined. Use a "Ready for Dev" workflow status and require AC completion before an issue can move to that status.
Tips
Use Linear's keyboard shortcut Cmd+K to quickly open the template picker when creating a new issue
Add a Linear workflow automation: when an issue moves to "In Review", require the AC checkboxes to be checked off
Include a "Performance Criteria" checkbox for any feature that involves data loading, e.g. "Page loads in under 2 seconds on a 4G connection"
Paste the Linear issue URL into your PRD in Vantage or Notion to create bidirectional traceability between the spec and the ticket
How Vantage helps
When Vantage generates tickets and pushes them to Linear, each issue is created with pre-written acceptance criteria derived from your PRD requirements. The AC is formatted as markdown checkboxes in the issue description, ready for QA to work through. You get the structure without the manual writing.