# Plan Epic

> Plan an entire epic: read the pre-plan and Jira epic, investigate codebase broadly, design architecture/data models/deliverable breakdown, and present for approval. Picks up docs/agomez/preplans/MLID-XXXX.md automatically when it exists. Usage: /plan-epic MLID-XXXX

- Skill: `alejandrogomezforte/plan-epic` (Agent Skill)
- Install (CLI): `npx skillmds@latest add alejandrogomezforte/plan-epic`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alejandrogomezforte/plan-epic/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: alejandrogomezforte (https://skillmd.com/u/alejandrogomezforte)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/alejandrogomezforte/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`