Linear Issue Tracking¶
Home / Guides & Runbooks / Linear Issue Tracking
How we structure work in Linear — the hierarchy, what belongs at each level, and the conventions that keep it legible as the team and the codebase grow.
Hierarchy¶
| Level | What it is | Timescale | Example |
|---|---|---|---|
| Initiative | A company milestone the whole team drives toward | Quarter (~3 months) | "Ship first fully-automated part end-to-end" |
| Project | A bounded outcome serving an initiative | Weeks to ~2 months | "CAM v1 Toolpath Generation" |
| Issue | A mid-sized step serving a project | Days to ~1 week | "Slot toolpath generation" |
| Sub-issue | A single PR-level step serving an issue | Hours to ~1 day | "Slot detection" |
| Label | A category that cuts across projects / initiatives | — | Domains ("Fixturing", "Linking"), components ("Ruffles", "Hardware Assets") |
Initiatives are milestones, not product areas¶
An initiative is a company milestone — a landmark outcome the org rallies behind on a month-to-quarter horizon, not a standing product area or a single dated feature. Frame it as what the company must achieve this quarter:
- "Ship first fully-automated part end-to-end"
- "AutoCAM running in production for internal jobs"
- "First paying customer onboarded"
A product-scoped effort like toolpath generation is a project under one of those initiatives — not an initiative itself. Rule of thumb: if a candidate initiative names a component or a feature rather than an outcome, it's probably a project.
Practical Guidelines¶
Group related PRs under an issue, each as a sub-issue¶
A common workflow: track the work for a mid-sized deliverable as sub-issues under one issue, then work each sub-issue one at a time as an individual PR. This keeps a reviewable PR mapped to exactly one sub-issue.
Use views heavily¶
Whenever you want a clear slice of issues matching certain filters, create a View. Views can be team-level or private.
Examples:
- Kanban: My Issues
- Kanban: Issues with the label "Fixturing"
- List: Issues under the "Ship first automated part" initiative
Use labels for cross-project / cross-initiative categories¶
Labels earn their place by cutting across the hierarchy. A good label:
- Spans a meaningful number of issues (~10+)
- Does not fully overlap an existing project
For example, "Benchmarking" would be a poor label because there's already a Benchmarking project — the label would carry no information the project doesn't.