Plan Epic

/plan-epic $ARGUMENTS

You are starting the epic-level planning phase. Your goal is to design the big picture: architecture, data models, integration strategy, and deliverable breakdown for an entire epic. You use opus-level reasoning for deep architectural decisions.

This skill does NOT plan individual tasks. It produces the master plan that individual tasks will reference. For task-level planning, use /plan-task.

Step 1 — Read the Jira epic

Use the Atlassian MCP to read the Jira issue $ARGUMENTS:

• Summary, description, and acceptance criteria
• Story points and issue type (should be Epic or Story with sub-tasks)
• Sub-tasks / child issues — list them all
• Links, attachments, and design references

Also read any linked issues or sub-tasks to understand the full scope.

Step 2 — Read the pre-plan

Check for a pre-plan at docs/agomez/preplans/$ARGUMENTS.md. Also check for docs/agomez/preplans/$ARGUMENTS-v2.md — /preplan writes that variant rather than overwriting an existing draft, so when both exist the -v2 file is the newer one. If several exist, ask the user which one is current rather than guessing.

If a pre-plan exists, it is the primary input to this skill. It is not background reading and it is not a suggestion. It is the shape the user has already worked out and agreed, usually over several sessions, and it outranks the Jira text wherever the two disagree — the ticket is what was asked for, the pre-plan is what was decided after reading the code.

Read it in full and treat it as follows:

• Its deliverable and sub-task breakdown is settled. D<n> deliverables and D<n>-T<m> sub-tasks carry over into the epic plan with the same names and the same boundaries. This skill adds depth to that breakdown — architecture, data models, dependency graph, risks — it does not re-derive it.
• Answered questions are decisions, not options. Any entry in the pre-plan's open-questions section marked Answered has already been settled by the user. Do not re-open it, do not present an alternative, and do not let the architect design around a different answer.
• Unanswered questions and "to complement" notes are the open items the epic plan is expected to close, or to carry forward explicitly if they are still not decidable.
• Recorded findings are evidence, not guesses. Where the pre-plan states what the current code does, use it to steer Step 4's investigation rather than rediscovering it from nothing.

If you believe a deliverable in the pre-plan is genuinely wrong — not merely shaped differently from how you would shape it — raise it with the user in Step 6 as a flagged concern. Never silently restructure it.

If no pre-plan exists, say so plainly and continue; the remaining steps work without one.

Step 3 — Read the branch strategy

Read docs/agomez/dx/epic-git-branch-strategy.md to understand the epic branch model.

Also check the current git branch with git branch --show-current.

If an epic plan-progress file already exists at docs/agomez/plans/, read it to understand what's already been decided. This skill may be run to create or update the epic plan.

Step 4 — Investigate the codebase (broad)

Launch the codebase-investigator agent with a prompt that includes:

• The full epic description and scope
• The pre-plan's deliverable breakdown and its recorded findings about the current code (from Step 2), so the investigator confirms and extends them rather than starting from zero
• All sub-tasks and their descriptions
• Key domain areas mentioned in the epic

The investigation should be broad — this is about understanding the landscape, not a single feature. Ask the investigator to find:

• All existing code related to the epic's domain (models, services, API routes, pages)
• Data shapes and relationships between entities
• Integration points with external systems
• Existing patterns for similar features
• Architecture constraints (auth, RBAC, feature flags, real-time)

Wait for the investigation results.

Step 5 — Design the epic architecture

Launch the solution-architect agent (opus model) with a prompt that includes:

• The full Jira epic details (from Step 1)
• The full pre-plan text (from Step 2), if one exists, with its status stated explicitly: the deliverable breakdown is approved, and its answered questions are decisions already taken
• The codebase investigation summary (from Step 4)
• The branch strategy (from Step 3)
• The epic plan template: docs/agomez/dx/epic-workflow.md

Tell the architect to focus on:

1. Architecture decisions — data models, service layer design, API contract design, real-time strategy, integration approach
2. Data model design — new collections, schema shapes, indexes, relationships to existing data
3. Deliverable breakdown — group sub-tasks into self-contained, testable deliverables that can be PRed to develop independently. When a pre-plan exists, this breakdown is already fixed: carry its deliverables and sub-tasks over by name and add depth to them.
4. Dependency graph — which deliverables depend on others, what's the critical path
5. Risk identification — technical risks, open questions, decisions that need stakeholder input

Tell the architect NOT to:

• Write a migration number anywhere in the plan — not the next number, not the current last journal entry, not "as a sanity check". Many engineers push to develop daily, so both migration sequences (Drizzle in packages/db/migrations and Mongo db-update) move constantly, and a number written into an epic plan is wrong within days while still reading as an input. Migrations are referred to by what they do; where the number matters, the plan states the rule instead of a figure — read it from the migration journal when the migration is generated, and read it again immediately before the branch merges
• Write detailed implementation steps for individual tasks (that's /plan-task's job)
• Copy patterns from existing code — apply best practices constrained by the tech stack
• Re-derive, rename, merge, split or re-order the pre-plan's deliverables and sub-tasks
• Re-open any pre-plan question marked Answered, or design against a different answer. If one of those answers makes the architecture unworkable, say so as a flagged concern instead of quietly overriding it

The architect writes the plan to docs/agomez/plans/$ARGUMENTS-plan-progress.md (or updates it if it already exists).

Step 6 — Present the plan for approval

After the architect completes:

1. Read the plan file that was written
2. Present the full plan to the user inline
3. If a pre-plan was used, state plainly how the plan relates to it: which pre-plan decisions it carries, which "to complement" notes it closes, and which it carries forward still open. Raise any flagged concern about a pre-plan deliverable or answered question here, as a concern for the user to rule on — never as a change already made
4. STOP and wait for approval

Tell the user:

• "Here's the epic plan. Review architecture decisions, deliverable breakdown, and data models. Let me know if you'd like changes, or approve to start task-level planning."
• Do NOT proceed to write any implementation code
• Do NOT plan individual tasks — the user will run /plan-task for each one

Important Rules

• No implementation code — this skill only produces the epic plan document
• The pre-plan wins — when docs/agomez/preplans/$ARGUMENTS.md exists, its deliverable breakdown and its answered questions are settled input. This skill deepens them; it never quietly redesigns them. Disagreement is raised to the user, not resolved unilaterally
• Always use both agents — investigator (sonnet) first, then architect (opus)
• Always stop for approval — never auto-proceed
• Big picture only — architecture, data models, deliverables, dependency graph. NOT implementation steps for individual tasks.
• No migration numbers in the plan — refer to a migration by what it does, never by number, for the reason given in Step 5. An epic plan lives for weeks, so a number in it is stale almost immediately. Check this when you read the plan back in Step 6 and strip any number the architect wrote in, replacing it with the read-the-journal rule. The same applies to anything you say when presenting the plan.
• Plan file: docs/agomez/plans/$ARGUMENTS-plan-progress.md