Linear Status Cleanup — Client Teams
Purpose: Standardize workflow states (issue statuses) across client teams so boards and views behave consistently. Each Linear team has its own workflow; this doc defines the recommended set and how to audit and clean up.
Scope: Client teams only (LMNT, CTA, Eden, etc.). Internal teams can follow the same pattern if desired.
References: linear-cleanup-taxonomy.md, linear-board-audit-sop.md, linear-full-cleanup-discovery-report-2026-03-17.md.
1. Recommended standard set (client teams)
Use exactly these ten states so boards and views are consistent across client teams. Linear workflow states have a type: backlog, unstarted, started, completed, canceled. Multiple states can share a type.
| Order | Name | Type | Notes |
|---|---|---|---|
| 1 | Backlog | backlog | Not yet scheduled. |
| 2 | Ready for work | unstarted | Ready to be picked up; before cycle assignment. |
| 3 | Next Cycle | unstarted | Scheduled for next cycle; keep if using cycles. |
| 4 | To do | unstarted | To be worked on (e.g. in current cycle). |
| 5 | In progress | started | Work in progress. |
| 6 | Requirements review | backlog | Requirements being reviewed or refined (before work starts). |
| 7 | Internal Review | started | Internal (e.g. PR / code) review. |
| 8 | Client Review | started | Waiting on client feedback. |
| 9 | Done | completed | Completed. |
| 10 | Canceled | canceled | Won’t do / duplicate. |
Higher-level categories (Linear Issue statuses): In Settings → [Team] → Issue statuses, Linear groups states into four (or five) categories. When creating or editing a state, assign the correct category so the board and filters behave as expected:
| Linear category | Our states in this category | Use for |
|---|---|---|
| Backlog | Backlog, Requirements review | Not yet scheduled; requirements review/refinement. Default for new issues. |
| Unstarted | Ready for work, Next Cycle, To do | Ready or scheduled but work not started. |
| Started | In progress, Internal Review, Client Review | Work in progress or in review. |
| Completed | Done | Finished work. |
| Canceled | Canceled | Won’t do / duplicate. |
Ensure each of our ten states is assigned to the category in the table above. After merging or renaming, remove any leftover states from the wrong category and archive them once empty.
2. Common variants → standard name
When cleaning up, map existing state names to the standard set (then rename or merge in Linear).
| If you see (variant) | Map to (standard) |
|---|---|
| ToDo in Cycle, Todo in Cycle, ToDo This Cycle, Todo In Cycle | To do |
| Ready for Work/Developme, Ready for Development, Ready for work | Ready for work |
| In Progress, Started, WIP | In progress |
| PR Review, Internal Review (duplicate) | Internal Review |
| Client Review, Waiting on client | Client Review |
| Done, Complete, Completed | Done |
| Canceled, Cancelled, Duplicate, Won’t do | Canceled |
| Next Cycle, Needs grooming | Next Cycle |
| Triage | Backlog (or archive if empty) |
| Escalated / Needs SME, Escalation / need SME, Needs Escalation / SME | In progress (or Internal Review if under review) |
| Requirements Started, Requirements in Review, Requirements In Review | Requirements review |
| Testing, Needs Revision, Blocked | In progress or To do (move by context; then archive the state) |
Rename in Linear: Settings → [Team] → Workflow. Merge by moving all issues from state A into the keeper state, then archive state A.
3. Cleanup steps
- Audit — Run the workflow-state audit script to list every client team’s states (name, type, position, issue count). Report:
knowledge/sales/linear-status-audit-YYYY-MM-DD.md(or stdout). - Review — Per team, decide: which names to rename to standard, which states to merge, which to archive (no issues).
- Apply — In Linear: Settings → [Team] → Workflow. Rename states; for merges, move issues to the keeper state then archive the duplicate. Alternatively use the Linear API (
workflowStateUpdate, move issues then archive state) if doing bulk. - Re-audit — Run the audit again to confirm and to keep a snapshot for the next cleanup.
Script: apps/platform/scripts/audit-linear-workflow-states.ts. Run from apps/platform: npx tsx scripts/audit-linear-workflow-states.ts. Writes a report to vault or prints to stdout. Example report: linear-status-audit-2026-03-18.md.
4. Constraints
- One default state per type — Linear may require a single default for backlog/unstarted/started/completed/canceled. Prefer one “To do”, one “In progress”, one “Done”, one “Canceled”.
- Issue count — Before archiving a state, move or close all issues in it; Linear may not allow archiving a state that has issues.
- Board audit — After status cleanup, run a board audit (linear-board-audit-sop.md) to propose status updates for issues that were in renamed/merged states.
5. Audit script usage
From apps/platform:
npx tsx scripts/audit-linear-workflow-states.tsOptional: --output ../../knowledge/sales/linear-status-audit-YYYY-MM-DD.md to write the report to vault (path relative to apps/platform). Requires LINEAR_API_KEY or BRAINFORGE_PLATFORM_LINEAR_APP_TOKEN.
The script lists each (client) team and, for each, all workflow states with: name, type, position, and optionally issue count. Use the output to decide renames and merges per team.