Linear Issues
An issue is the most basic unit of work in Linear. Every task, bug report, feature request, or improvement gets its own issue. Teams track, discuss, and close work entirely through issues.
What Makes a Good Issue
A good issue is clear, specific, and actionable. Anyone on the team should read the issue title and understand the task without needing extra context. Vague issues like "Fix stuff" or "Improve performance" cause confusion. Clear issues like "Fix login timeout on Safari 17" or "Reduce homepage load time below 2 seconds" tell the assignee exactly what to do.
Good vs Poor Issue Writing
| Poor Issue | Good Issue |
|---|---|
| Fix the bug | Fix null pointer error when user submits empty cart |
| Update UI | Update button color on checkout page to match brand guide |
| Performance | Reduce API response time for /products endpoint from 800ms to under 200ms |
| Investigate crash | Investigate app crash on Android 13 when notifications are disabled |
Create an Issue
Press the keyboard shortcut C from anywhere in Linear to open the quick issue creation panel. Alternatively, click New Issue inside any team or project view.
Issue Creation Fields
| Field | Purpose | Required |
|---|---|---|
| Title | One-line summary of the task | Yes |
| Description | Full context, steps to reproduce, acceptance criteria | No (but strongly recommended) |
| Assignee | The person responsible for completing the issue | No |
| Status | Where the issue stands in the workflow | Auto-set to Todo |
| Priority | How urgent the issue is | No |
| Project | The project this issue belongs to | No |
| Label | A tag that categorizes the issue type | No |
| Due Date | When the issue must be completed | No |
Issue ID System
Every issue gets a unique ID automatically. The ID combines the team identifier with a sequential number.
Issue ID: ENG-142
┌── Team Identifier (Engineering = ENG)
│
ENG - 142
│
└── Sequential number (142nd issue created in Engineering)
Use the issue ID when referencing work in Slack messages, pull request descriptions, or emails. Type #ENG-142 in any Linear text field to create a clickable link to that issue.
Issue Lifecycle
An issue travels through workflow states from creation to completion. The default workflow covers the most common stages.
Issue Created
│
▼
[Todo] ──── No one has started this yet
│
▼
[In Progress] ── Assignee is actively working
│
▼
[In Review] ──── Work is done, awaiting feedback
│
▼
[Done] ──────── Work is accepted and complete
│
▼
[Cancelled] ───── Work is no longer needed
Sub-Issues
Complex tasks often need breaking down into smaller steps. Linear lets you create sub-issues under any parent issue. Sub-issues appear as a collapsible list inside the parent.
Sub-Issue Example
ENG-50: Redesign user profile page (Parent Issue)
│
├── ENG-51: Update profile photo upload component
├── ENG-52: Add social link fields to profile form
└── ENG-53: Fix profile page mobile layout
The parent issue shows a completion counter like "1 / 3 sub-issues done" so anyone can see progress at a glance without opening each child issue.
Issue Description Best Practices
The description field supports Markdown formatting. Use it to give the assignee everything they need to start and finish the work.
Recommended Description Structure
| Section | What to Include |
|---|---|
| Background | Why this issue exists and what problem it solves |
| Steps to Reproduce (bugs) | Exact steps another person can follow to see the bug |
| Acceptance Criteria | The conditions that confirm the issue is done |
| References | Links to designs, specs, related issues, or documentation |
Commenting on Issues
Team members discuss an issue in its comment thread. Comments support Markdown, file attachments, @mentions, and emoji reactions.
Use @username inside a comment to notify a specific person. That person receives a notification and a direct link to the comment. This keeps all issue-related discussion in one place instead of scattered across emails and chat.
Closing and Archiving Issues
Mark an issue as Done when the work is complete and accepted. Marking it Done moves it out of the active issue list but keeps it searchable. Linear auto-archives Done issues after a configurable number of weeks, defined in the team settings.
Cancelled issues also leave the active list. Use Cancelled instead of Done when the task will no longer be done — for example, when requirements change and the feature is dropped.