name: linear-issue-from-plan
description: Use when the user wants to create a Linear issue from a feature plan document (plan.md) generated by /engineering/plan-feature or /engineering/ship-feature. Triggers on: "create linear issue from plan", "post this to linear", "make an issue for this plan", "communicate this plan on linear".
Linear Issue from Plan
Turn a plan.md from the Dalgo feature pipeline into a Linear issue that communicates the implementation approach to the team.
What to Extract
| plan.md section | Linear field |
|---|
| Feature name + one-liner | title |
| Overview (§1) | Description intro |
| Services affected table (§2 or §3) | Description — Services table |
| HLD (§3) | Description — Architecture summary (keep brief) |
| Milestones (§7) | Description — Milestones (one H3 per milestone, bullet tasks) |
| Open Questions (§8) | Description — Open Questions numbered list |
| Risks (§8) | Description — Key Risks bullets |
Issue Fields
- team:
Dalgo (default; ask if unclear)
- priority:
2 (High) for features touching multiple services; 3 (Medium) otherwise
- assignee:
me unless user specifies someone
- title pattern:
<Feature name> — <one-liner describing the core change>
Description Structure
## Overview
<1-3 sentences from plan §1. Link to plan.md and spec.md relative paths.>
---
## Services Affected
<paste the services table from the plan>
---
## Architecture
<2-4 bullet points from HLD — the key design decisions only, not the full diagrams>
---
## Milestones
### M1: <name> *(<services>)*
- <task bullets>
- **Acceptance:** <acceptance criterion>
[for milestones with significant UX impact (M3 onwards typically), add a PM-readable intro — see below]
---
## Open Questions
1. **<question title>** — <detail>
---
## Key Risks
- **<risk>** — <mitigation>
PM-Readable Milestone Format
For milestones that touch user-facing behaviour (navigation, permissions, settings, ownership, comms), add a "What users will see" paragraph before the bullet tasks. Each bullet then pairs a plain-English outcome with the technical detail in italics:
### M3: <User-facing name> *(<services>)*
**What users will see:** <1-2 sentences describing the user-observable change — no jargon.>
- **<Plain-English outcome>** — <what it means for users> *(technically: <component/endpoint/model detail>)*
- **<Plain-English outcome>** — <what it means for users> *(technically: <component/endpoint/model detail>)*
Rule of thumb: if a milestone only touches migrations, seeds, or backend plumbing with no visible user change (e.g. M1, M2), skip the "What users will see" block — it would be misleading. Add it when a PM would notice the change in the UI.
Steps
- Read the plan file (confirm path with user if ambiguous — could be
features/<name>/v<n>/plan.md)
- Extract the fields above
- Call
list_teams if you don't know the team ID yet (Dalgo team is the default)
- Call
save_issue — do not pass id (that's for updates)
- Return the issue URL and ID to the user
MCP Tool
The Linear MCP is mcp__93e2448a-30ab-40b2-9393-36ee6ab0a497__save_issue. Load it via ToolSearch if not already in scope:
ToolSearch: select:mcp__93e2448a-30ab-40b2-9393-36ee6ab0a497__save_issue,mcp__93e2448a-30ab-40b2-9393-36ee6ab0a497__list_teams
What NOT to Include
- Full migration SQL or code snippets from LLD — keep description scannable
- ASCII architecture diagrams — replace with 2-4 bullet summary
- Research citations (§ references) — those are internal; strip them from the issue
