# Linear Brasa Plan > Read the Design Document from a brasa Linear issue and produce an implementation plan stored as an `Implementation Plan` Document on the same issue (not a description section). Moves the issue to `Planned` on success. Use whenever the user says "plan WIL-X", "write the plan for WIL-X", or wants to turn an already-refined issue into an actionable plan. - Skill: `wilsonfreitas/linear-brasa-plan` (Agent Skill) - Install (CLI): `npx skillmds@latest add wilsonfreitas/linear-brasa-plan` - Raw SKILL.md: https://api.skillmd.com/api/skills/wilsonfreitas/linear-brasa-plan/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: wilsonfreitas (https://skillmd.com/u/wilsonfreitas) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/wilsonfreitas/linear-brasa-plan --- # Linear Brasa — Plan (Implementation Plan Document → Planned) Take an already-refined brasa Linear issue (one with a `Design` Document) and produce a bite-sized implementation plan stored as an **Implementation Plan** Document on the same issue. **Announce at start:** "I'm using the linear-brasa-plan skill to write the plan for WIL-X." **Always use the Linear MCP tools** (`mcp__plugin_linear_linear__*`). **Workspace constants:** - Team: `Wilsonfreitas` — `6c3534b0-9f98-476c-a1d6-3f99119e9f88` - Project: `brasa` — `700095cc-dd63-405b-b285-1895aabce09d` --- ## Shared Convention A — Document upsert (never create duplicates) MCP cannot delete a Document. Always upsert: ``` 1. get_issue(id=WIL-X) → read documents: [{id, title}, ...] 2. Find the entry whose title EXACTLY equals "Implementation Plan". 3. If found: save_document(id=, content=) # update in place If not found: save_document(issue=WIL-X, title="Implementation Plan", content=...) # create once 4. NEVER call save_document(issue=...) when "Implementation Plan" already exists. ``` ## Shared Convention B — Status transition (read-back verified, never on abort) ``` 1. Only after the skill's main work succeeded: save_issue(id=WIL-X, state="") # state, NOT status 2. Read the returned JSON; confirm "status":"" before announcing. 3. If the skill aborts/errs before completing, do NOT move the status. ``` --- ## Phase 1 — Preconditions 1. Require `WIL-X`. If missing, ask once: "Which issue? (e.g., WIL-42)". 2. Fetch the issue via `mcp__plugin_linear_linear__get_issue`. Read title and the `documents` array. 3. Look in `documents` for an entry with title exactly `Design`: - If absent, stop: "Issue WIL-X has no Design Document. Run linear-brasa-brainstorm first." - If found, note the id for Phase 2. 4. Look in `documents` for an entry with title exactly `Implementation Plan`: - If found: call `get_document(id=)`, show its content verbatim, then ask: "Issue already has an Implementation Plan Document. Re-plan and overwrite it? (y/n)". Exit on decline. - If not found: proceed. --- ## Phase 2 — Write the Plan ### 2a — Feed Design Document into writing-plans 1. Call `mcp__plugin_linear_linear__get_document(id=)` to retrieve the full design. 2. Invoke `superpowers:writing-plans`, passing the Document content as the input spec. Follow its full flow: - Scope check (decomposition if the spec is too broad). - File-structure mapping. - Bite-sized tasks (2–5 minute steps) with exact file paths, complete code, exact commands, and the no-placeholders rule. - Mandatory plan header (`# ... Implementation Plan` with `Goal`, `Architecture`, `Tech Stack`). 3. **Override: no git steps.** `superpowers:writing-plans` emits `git add` / `git commit` steps and preaches frequent commits. Strip them — the plan MUST NOT contain any git, commit, push, or branch steps. Version control is owned entirely by `linear-brasa-executor` (branch-per-issue, one commit per task, gated merge to main). Plans describe what code changes to make and how to verify them; the executor decides how they land in git. 4. **Required header note.** The plan header MUST include this exact line directly under the `Tech Stack` line: > Version control (branch, commit, merge) is handled by linear-brasa-executor; this plan contains no git steps. ### 2b — Override the "Save plan" step **Do NOT write to `docs/superpowers/plans/*.md` or to the issue description.** Instead, once the plan is approved by the user, apply Convention A to write it to the **Implementation Plan Document**: 1. Re-read the current `documents` list via `get_issue` (in case it changed during planning). 2. Apply Convention A with target title `Implementation Plan`. 3. The plan content must use `- [ ]` checkbox syntax so the executor can tick steps off. ### 2c — Self-review After saving the Plan Document: 1. Call `get_document(id=)` — read the Design. 2. Call `get_document(id=)` — read the saved Plan. 3. Verify: - Spec coverage: every Design requirement maps to a plan task. - Placeholder scan: no TBD / TODO / incomplete steps. - Name consistency: function names, file paths, and types match across tasks. 4. Fix any issues via `save_document(id=, content=)`. Nothing is written to disk. Nothing is modified in the issue description. --- ## Phase 3 — Status Transition to Planned Apply Convention B with `state="Planned"`: 1. Call `save_issue(id=WIL-X, state="Planned")`. 2. Read the returned JSON; confirm `"status":"Planned"` before announcing. 3. If the call fails or returns a different status, report the error and do NOT announce Planned. Close out with exactly: > ✅ Plan finalized in WIL-X (status: Planned). When you're ready to execute, use linear-brasa-executor. Share the issue URL. --- ## General Notes - Write plan content in **English**. - Do NOT offer the "Subagent-Driven vs. Inline Execution" choice from `writing-plans`, and do NOT auto-invoke the executor. - If the user interrupts mid-plan, pause and resume only on their confirmation. - If the design turns out to require decomposition (multiple independent subsystems), stop and tell the user rather than writing a multi-feature plan into a single issue.