Problem

[1-2 sentences: Why does this feature need to exist?]

Solution

[1-2 sentences: What are we building to solve this?]

High-Level Implementation

[Bullet points: Key technical decisions, patterns]

Codebase Investigation Findings

[What patterns to follow, similar features, code locations]

Out of Scope / Deferred

[Explicitly list what we're NOT doing]


## Issue Structure: Sub-Issues / Tasks

```markdown
## Objective
[1-2 sentences: What specific thing needs to be done?]

## Acceptance Criteria
- [ ] [Specific, testable criterion 1]
- [ ] [Specific, testable criterion 2]
- [ ] [Specific, testable criterion 3]

## Implementation Notes
- Relevant files: [paths]
- Patterns to follow: [reference]
- Dependencies: [other issues]

Writing Good Acceptance Criteria (SMART)

Specific: Clear about what exactly needs to happen
Measurable: Can objectively verify if it's done
Achievable: Within scope of this single issue
Relevant: Directly related to the objective
Testable: Can be validated by running/checking

Principles for Issue Writing

Self-Contained Context - Everything needed to understand and execute
What, Not How - Describe outcome, not implementation
Appropriate Granularity - Not too big, not too small
Link to Resources - Design, API docs, related issues
State Assumptions - Make implicit expectations explicit

Anti-Patterns to Avoid

Vague objectives: "Improve the dashboard"
Missing acceptance criteria: Assuming it's obvious
Implementation prescription: Over-specifying the how
Hidden dependencies: Not mentioning blockers
Scope creep: Adding "nice to haves"

Mermaid Diagrams in Linear Issues

ALWAYS include Mermaid diagrams when applicable. Linear supports Mermaid diagrams natively in issue descriptions. Use them to visualize:

User flows and interaction sequences
Data flow and processing pipelines
State machines and lifecycle transitions
Component relationships and dependencies
API/service interaction patterns
Entity relationships and data models

Mermaid Syntax in Linear

Use standard markdown code fences with mermaid as the language identifier:

```mermaid
flowchart TD
    A[Start] --> B[End]
```

Common Diagram Types

Type	Use Case	Syntax
`flowchart TD`	Top-down user flows, process flows	`flowchart TD`
`flowchart LR`	Left-right horizontal flows	`flowchart LR`
`sequenceDiagram`	API calls, service interactions	`sequenceDiagram`
`stateDiagram-v2`	State machines, status transitions	`stateDiagram-v2`
`erDiagram`	Database schemas, entity relationships	`erDiagram`
`classDiagram`	Class relationships, component structure	`classDiagram`

When to Include Diagrams

Always include a diagram when:

Describing a multi-step process or user flow
Explaining how components interact
Documenting state transitions
Showing data flow between systems
Illustrating API call sequences
Mapping entity relationships

The diagram should appear in:

Parent issue "High-Level Implementation" section
Sub-issue descriptions when flow context is needed
Bug reports when showing expected vs actual flow
Any issue where visual clarity aids understanding

Remember: A good issue can be executed by anyone who reads it.

issue-writing

Issue Writing Skill

When to Use

Issue Structure: Parent Feature Issues