rai-epic-plan

Epic Plan

Purpose

Transform the story list from /rai-epic-design, plus any ux-design.md artifact, into a sequenced implementation plan with milestones, parallel work streams, and progress tracking.

Mastery Levels (ShuHaRi)

• Shu: Follow all steps, create sequenced plan with walking skeleton + MVP milestones
• Ha: Adjust milestone granularity based on epic size, skip timeline for small epics
• Ri: Domain-specific sequencing patterns, team velocity models

Context

When to use: After /rai-epic-design has produced a scope document with stories. If the epic is user-facing and ux-design.md exists, consume it before sequencing. Run this before the first story starts.

When to skip: Very small epics (2-3 stories) with obvious linear sequence. Emergency fixes.

Inputs: Epic scope document (work/epics/e{N}-{name}/scope.md), calibration data (if available).

Steps

PRIME (mandatory — do not skip)

Before starting Step 1, you MUST execute the PRIME protocol:

1. Chain read: Read work/epics/e{N}-{name}/design.md if present, carrying forward its scope and architectural decisions. If ux-design.md exists in the same directory, read it too and carry forward workflow/trust-boundary constraints. If neither is present (legacy epic predating these artifacts), note and continue — fall back to scope.md.
2. Graph query: Execute tier1 queries from this skill's metadata. Use raise_graph_query MCP tool with cwd="{project_or_worktree_path}". If MCP tools are not available, fall back to:

   rai graph query
   

   If graph is unavailable, note and continue.
3. Present: Surface retrieved patterns as context. 0 results is valid — not a failure.
4. Emit start: Signal lifecycle start for observability.

Step 1: Review Epic Scope

Load and understand the epic scope document:

• Story list with sizes and dependencies
• Done criteria and risks
• Architectural decisions that affect sequencing
• UX workflow, surfaces, and trust boundaries from ux-design.md if it exists

Step 2: Sequence & Rationalize

Order stories using these strategies (in priority order):

For each story, document: position, rationale, dependencies (hard/soft/external), what it enables.

JIT: Before choosing sequencing strategy, query graph for ordering patterns and calibration data → aspects/introspection.md § JIT Protocol

Identify parallel opportunities: Stories with no mutual dependencies, different codebase areas, or independent concerns can run concurrently.

Step 3: Define Milestones

Create 2-4 intermediate checkpoints:

Per milestone: stories included, success criteria (verifiable), demo capability.

JIT: Before defining milestones, query graph for calibration patterns and checkpoint strategies → aspects/introspection.md § JIT Protocol

Integration checkpoint: For epics with multiple components (client/server, CLI/API, frontend/backend), schedule an E2E integration milestone before the final story. This checkpoint runs real infrastructure (docker compose, actual DB) and verifies cross-story contracts (auth headers, payload schemas, parameter limits). Unit tests with mocks cannot catch these mismatches — only real E2E validates the seams between stories.

Step 4: Setup Tracking

Add progress tracking to epic scope using templates/plan-section.md:

• Story sequence table with status/actual/velocity columns
• Milestone checklist with target dates
• Velocity assumptions from calibration data (if available)

Step 5: Update Scope Document

Append the implementation plan section to work/epics/e{N}-{name}/scope.md via CLI (preserves existing content + publishes to Confluence):

Use raise_docs_write MCP tool with doc_type="epic-scope", title="E{N}: {epic-name} scope + plan", content="existing work/epics/e{N}-{name}/scope.md contents plus ## Implementation Plan, ## Milestones, and ### Sequencing Risks sections", output_path="work/epics/e{N}-{name}/scope.md", cwd="{project_or_worktree_path}". If MCP tools are not available, fall back to:

rai docs write epic-scope \
  --title "E{N}: {epic-name} scope + plan" \
  --stdin \
  --output-path work/epics/e{N}-{name}/scope.md << EOF
$(cat work/epics/e{N}-{name}/scope.md)

## Implementation Plan
{story sequence with rationale}

## Milestones
{milestones with success criteria}

{parallel work streams if any}

{progress tracking table}

### Sequencing Risks
{top 3 risks}
EOF

Note: unquoted heredoc so $(cat ...) expands the existing scope content.

Present plan to human for review before starting first story.

Output

Backlog transition to implement status is engine-owned (RAISE-15034): Engine performs the transition via apply_phase_transition at phase completion. No skill-initiated transition call required or allowed.

STOP HERE. Return your summary to the orchestrator. Do NOT invoke any further skill.

Quality Checklist

• All stories sequenced with rationale
• Critical path identified
• At least 2 milestones (walking skeleton + MVP minimum)
• Dependencies verified — no cycles, blockers identified
• Parallel opportunities documented (or explained why sequential)
• Progress tracking in scope document
• NEVER over-plan — plans are hypotheses, not commitments
• NEVER sequence by size alone — use risk-first as default
• Multi-component epics include E2E integration checkpoint

References

• Plan template: templates/plan-section.md
• Previous: /rai-epic-design (produces scope input) + /rai-epic-ux-design when the epic is user-facing
• Next: /rai-story-design for first story
• Close: /rai-epic-close
• Calibration: .raise/rai/memory/calibration.jsonl