Linear & Issue Tracking Best Practices

Issue Writing Guidelines

Clear Titles

Write titles that describe the problem or outcome:

• •Good: "Users can't reset password on mobile Safari"
• •Bad: "Password bug"
• •Good: "Add export to CSV for user reports"
• •Bad: "Export feature"

Effective Descriptions

Include:

1. •Context: Why this matters
2. •Current behavior: What happens now (for bugs)
3. •Expected behavior: What should happen
4. •Steps to reproduce: For bugs
5. •Acceptance criteria: Definition of done

Templates

Bug report:

## Description
Brief description of the issue.

## Steps to Reproduce
1. Step one
2. Step two
3. Issue occurs

## Expected Behavior
What should happen.

## Actual Behavior
What happens instead.

## Environment
- Browser/OS
- User type

Feature request:

## Problem Statement
What problem does this solve?

## Proposed Solution
High-level approach.

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

Label Taxonomy

Recommended Labels

Type labels:

• •bug - Something isn't working
• •feature - New functionality
• •improvement - Enhancement to existing feature
• •chore - Maintenance, refactoring

Area labels:

• •frontend, backend, api, mobile
• •Or by feature area: auth, payments, onboarding

Status labels (if not using workflow states):

• •needs-triage, blocked, needs-design

Label Best Practices

• •Keep label count manageable (15-25 total)
• •Use consistent naming convention
• •Color-code by category
• •Review and prune quarterly

Priority and Estimation

Priority Levels

• •Urgent (P0): Production down, security issue
• •High (P1): Major functionality broken, key deadline
• •Medium (P2): Important but not urgent
• •Low (P3): Nice to have, minor improvements

Estimation Tips

• •Use relative sizing (points) not hours
• •Estimate complexity, not time
• •Include testing and review time
• •Re-estimate if scope changes significantly

Cycle/Sprint Planning

Cycle Best Practices

• •Duration: 1-2 weeks typically
• •Capacity: Plan for 70-80% to allow for interrupts
• •Carryover: Review why items didn't complete
• •Retrospective: Brief review at cycle end

Planning Process

1. •Review backlog priorities
2. •Pull issues into cycle
3. •Break down large items (>5 points)
4. •Assign owners
5. •Identify dependencies and blockers

Project Organization

Projects vs Initiatives

Projects: Focused, time-bound work (1-3 months)

• •Single team typically
• •Clear deliverable
• •Example: "Mobile app v2 launch"

Initiatives: Strategic themes

• •May span multiple projects
• •Longer-term goals
• •Example: "Platform reliability"

Roadmap Tips

• •Keep roadmap items high-level
• •Update status regularly
• •Link to detailed issues/projects
• •Share with stakeholders

Triage Workflows

Triage Process

1. •Review new issues daily
2. •Add missing information (labels, priority)
3. •Assign to appropriate team/person
4. •Link related issues
5. •Move to backlog or close if invalid

Closing Issues

Close with clear reason:

• •Completed: Work is done
• •Duplicate: Link to original
• •Won't fix: Explain why
• •Invalid: Missing info, not reproducible

GitHub Integration

Linking PRs to Issues

• •Reference Linear issue ID in PR title or description
• •Linear auto-links and updates status
• •Use branch names with issue ID for automatic linking

Workflow Automation

• •PR opened → Issue moves to "In Progress"
• •PR merged → Issue moves to "Done"
• •Configure in Linear settings