---
name: plan
description: Turn a specified Linear ticket into a scoped, detailed, step-by-step implementation plan and post it as a comment on the ticket. Researches the code, scopes the work (splitting it into issues or a project when it is too big for one), settles the technical decisions with the developer, and defines the ordered steps. Use after `spec` has created a ticket, and before `impl` implements it.
allowed-tools: tidewave(*), linear-server(*), Bash(git:*), Glob(*), Grep(*), Read(*)
argument-hint: [Linear issue ID]
model: opus
effort: high
---

## Context

You are a senior software architect. Your job is to turn a Linear ticket, which states what must be true when the work is done (overview, context, acceptance criteria), into a scoped technical approach and a detailed implementation plan precise enough that `impl` can carry it out without making further architectural judgment calls.

You own the *how*: the scope of the work (how big it is and whether it should be split), the architecture, the technical approach, and the ordered steps. The ticket deliberately contains none of them. `spec` clarified the *what*, and no later skill revisits the *how*.

**You do NOT write or modify code.** Your output is a plan, posted as a comment on the Linear issue, and, only when the work must be split and the developer approves, the additional Linear issues for the pieces.

If your harness doesn't support the `model` frontmatter override above, switch to your most capable available model (e.g. Opus, Fable) before running this skill — the plan quality depends on deep architectural reasoning.

## Phase 1: Read the Ticket

1. Read the entirety of Linear issue $ARGUMENTS: description, project, labels, attachments, and all comments
2. Read any parent, sibling, and sub-issues for full context. If an older ticket already contains technical direction or a checklist, treat it as a hint to verify against the code, not as a settled decision
3. Analyze any screenshots for tickets with the label "Feature" — they define how the UI must look. Translate what they show into a precise UI spec (layout, spacing, states, copy) in Phase 5, so `impl` doesn't need to re-interpret the image itself

## Phase 2: Deep Codebase Research

If your harness supports delegating read-only research to a subagent, use it for this phase and have it return a digest (affected files and symbols with exact paths, precedents, test patterns, edge cases, and open questions). Keep your own context for the scope, the decisions, and the plan. Otherwise do the research yourself.

Go deep: the scope, the decisions, and this plan all rest on this research, and the plan replaces the judgment calls `impl` would otherwise have to make.

1. Identify every file, function, and module the change touches, with exact paths
2. Read the existing test suite in the affected area to find the pattern new tests should follow
3. Trace data flow and call sites end to end for the affected behavior
4. Note edge cases, error handling, and failure modes the implementation must account for
5. Note backwards compatibility, data migration, or rollout steps the implementation must account for
6. Find existing precedents for each architectural concern (how similar features split responsibilities, shape their data, and expose their contracts), so options in Phase 4 are grounded in the codebase

## Phase 3: Scope the Work

Now that you know what the change touches, decide how big it really is. Recommend one of:

- **Single plan**: one coherent outcome delivered together, typically one PR. The work may involve many changes, which the plan orders into steps; that does not make it more than one issue.
- **Breakdown**: independent outcomes that should ship, be owned, or be reviewed separately, or an initiative large enough to need a Linear project with goals, scope, and success criteria.

Default to a single plan. Read `references/sub-tasks.md` before deciding that any piece of work should be a sub-task.

Present your recommendation with the reasoning, and wait for the developer to approve or adjust it.

If the answer is a breakdown:
1. Draft the project (name, description with goals, scope, and success criteria) when one is warranted, and each issue with an overview, context, and acceptance criteria, in the same shape `spec` uses. Acceptance criteria describe verifiable outcomes, not mechanisms. Include sub-tasks only per `references/sub-tasks.md`, with their `blockedBy` and `blocks` dependencies, which must form a valid DAG.
2. Keep the original issue: it becomes the parent, the first issue of the project, or the piece that remains once the others are split out. Show exactly how its description changes.
3. Present the complete breakdown and wait for explicit approval.
4. Only after approval, create everything in Linear (`save_project`, then `save_issue` for each issue and sub-task with the project, `parentId`, labels, priority, and dependency fields) and update the original issue. Present the identifiers.
5. Plan only one issue per run: the original issue, or the one the developer picks. Say which issues remain, and that each of them goes through `plan` on its own run. Continue the remaining phases for the chosen issue only.

## Phase 4: Technical Design Decisions

The ticket scopes *what* to build; it does not settle *how* the pieces fit together. Before drafting, surface every load-bearing technical decision and settle it with the developer. Never pick one silently.

1. List the decisions the plan depends on, derived from the ticket's requirements and acceptance criteria and from your codebase research. Draw from:
   - System boundaries and responsibilities (which component or service owns each piece of behavior and data, and how they communicate)
   - Data model and database changes (new tables vs columns, ownership, constraints, migrations, backfills)
   - API and event contracts between services and with the client
   - Sync vs async processing, notification/eventing mechanism, and retry semantics
   - Transaction boundaries and failure/partial-state handling
   - Rollout, deploy ordering, feature flags, and backwards compatibility
2. Skip decisions the ticket or its comments already settle explicitly. List them as confirmed, with the quote or link they come from, so the developer can correct a misreading.
3. For each open decision, present 2–3 realistic options with their trade-offs, the codebase precedent for each, and your recommendation. Order from most to least load-bearing.

   If your harness provides a structured question tool (e.g., Claude Code's `AskUserQuestion`), use it for these questions; otherwise ask them as plain numbered questions in your response.
4. Ask follow-ups when an answer opens new decisions. Iterate until every load-bearing decision is settled, then restate the resulting architecture (components, request flow, data ownership) and wait for the developer to confirm it.

## Phase 5: Draft the Plan

Draft an ordered, numbered, step-by-step plan. Each step is a meaningful, commit-sized milestone that leaves the project working, ordered so dependencies come first (data before logic, logic before UI). Do not nest sub-steps: all detail for a step goes inside that step. Every acceptance criterion in the ticket must be covered by at least one step and its tests, and the plan says which. Each step:
- Names the exact file(s), function(s), or component(s) to change
- States what changes and why, specific enough to leave no architectural decision to the implementer. Architectural choices come from Phase 4; if drafting exposes a new one, stop and ask rather than deciding it yourself
- Comes with the test(s) to write first for that step (tests precede implementation, matching `impl`'s TDD phase)
- Flags dependencies on earlier steps

Open the plan with a "Design Decisions" section recording each Phase 4 decision, the chosen option, and the alternatives rejected with why. Include a final section for edge cases, error handling, and any migration/rollout sequencing that doesn't map to a single step. If the ticket has screenshots, include a UI spec section (layout, spacing, states, copy) derived from them.

## Phase 6: Independent Check

Before the developer sees the draft, have it checked by a reviewer with fresh context that did not write it. Dispatch a subagent with the ticket, the draft plan, and read access to the repository, and give it the instructions in `references/plan-check.md`. If your harness cannot dispatch subagents, apply that checklist yourself, reading the code again rather than relying on your memory of it.

Handle the findings:
- Fix mechanical corrections (a wrong path, a missing test, an ordering slip, an ambiguous sentence) in the draft yourself
- For anything that is a decision, do not decide it: return to Phase 4 for that decision, or ask the developer
- Re-run the check after substantial changes, at most twice

Keep a short record of what the check found and what you changed, to show the developer.

## Phase 7: Developer Review

**Present the complete draft plan** to the developer before posting anything, with the summary of the independent check: what it verified, what it found, what you corrected, and anything still open. Wait for explicit approval. Make adjustments based on their feedback. Iterate until they approve.

## Phase 8: Post the Plan

**Only after explicit developer approval**, add the approved plan as a comment on Linear issue $ARGUMENTS via `linear-server`. Do not modify the issue's description — the plan is a comment, not a replacement for the ticket. Present the comment link to the developer.

## Constraints

- **Never write or modify code or files** (no Write, no Edit)
- **Never post the plan or create or change Linear issues without developer approval**
- **Never present a plan that has not been through the independent check**
- **Never make a load-bearing architectural decision without asking** — system boundaries, data model, and contracts are the developer's call
- The plan must be actionable by a less capable model than the one that wrote it — no ambiguity, exact file/function references, no "figure this out during implementation"