Linear Issue Standard

This standard defines the requirements for creating and managing issues in our Linear workspace, ensuring consistent tracking, assignment, and status updates across the team.

Title Format

Always prefix the issue title with a bracketed abbreviation representing the system domain or project:

Format: [ABRV] Proper Issue Name Please
Example: [PAY] Include merchantName metadata field in subscription renewals

Issue Fields

State: When a ticket is active/assigned, set its status to In Progress.
Assignee: Assign the issue to the active developer (e.g., "me" or "law@foxy.ai").
Issue Lead: Every non-trivial Issue has one owner — accountable for scope, Subissue breakdown, estimates, risks, readiness for the next gate, and handoff to QA. Usually the assignee.
Estimate: The Issue carries a Fibonacci estimate (1 · 2 · 3 · 5 · 8 · 13), summed from its Subissues or set as expected total effort — Issue ≤ 8 points, each Subissue ≤ 5. Every Subissue must be estimated.
Labels: A Type (Bug/Feature/Improvement/Maintenance/R&D) and a Service; a Severity (P0–P3) on defects. See the Ways of Working standard for the full label model and lifecycle.

Full Issue Template

Use the following Markdown structure in the issue description:

Summary

A short, high-level overview of the project. No details or solutions yet. Someone unfamiliar with the context should be able to read this in under a minute and decide whether it's relevant to them or worth reading further.

Why?

Why do we want or need to do this now? What triggered it? Explain motivation and urgency, and what happens if we don't do it.

Outcome

What does success look like? List the concrete benefits we expect.

Key metrics that should improve:
Who benefits:
How we'll track it:
How we'll know it failed:

Design

What changes from a user or system perspective? Share mockups, sketches, diagrams, or descriptions.

Approach

Key technical decisions, architecture changes, services affected. Link relevant proto definitions, API docs, or prior art.

Scope

In scope:
Out of scope:

Problems / Considerations

Known risks, trade-offs, open questions.

Who can unblock if blocked:

Rollback

How to reverse this if it goes wrong. Mandatory for Issues touching payments, KYC, moderation, security, or data/analytics semantics — the reversal plan must exist before execution. Optional elsewhere.