rai-story-plan

Story Plan

Purpose

Decompose a story into atomic executable tasks with dependencies, verification criteria, and a deterministic execution order.

Mastery Levels (ShuHaRi)

See raise.mastery in frontmatter.

Context

When to use: After /rai-story-design has grounded integration decisions (or directly for simple stories).

Prerequisite: Design document at work/epics/e{N}-{name}/stories/s{N}.{M}-design.md (optional for simple stories).

Inputs: Story with acceptance criteria, design document (if exists).

Steps

PRIME (mandatory — do not skip)

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

1. Graph query: Execute tier1 queries from this skill's metadata using the raise_graph_query MCP tool with cwd="{project_or_worktree_path}". If MCP tools are not available, fall back to:

   rai graph query
   

   0 results is valid.

Step 1: Verify Design

ls work/epics/e*/stories/{story_id}-design.md 2>/dev/null || echo "INFO: No design"

JIT: Before verifying design completeness, query graph for complexity assessment patterns → aspects/introspection.md § JIT Protocol

Step 2: Decompose into Tasks

Divide story into atomic, individually verifiable tasks. One commit per task.

Per task:

• Description, files to create/modify
• TDD cycle: RED (failing test) → GREEN (minimal code) → REFACTOR
• AC reference: link to story.md Gherkin scenario (if exists)
• Verification: specify the rai gate check commands with explicit --scope (see Gate Policy below)
• Size (XS/S/M/L) and dependencies

Always include as final task: Manual integration test — validate end-to-end with running software.

Gate Policy (mandatory in every plan):

Include this section verbatim in the plan document — it keeps the test execution rules in context during /rai-story-implement:

NEVER run test commands directly (e.g. uv run pytest, npm test) — always use rai gate check. Direct invocation floods context with raw output and bypasses gate tracking.

Each task's Verification section MUST use rai gate check gate-tests --scope <path> with the concrete test path for that task. Generic or unscoped test commands are not acceptable.

Step 3: Order & Dependencies

JIT: Before ordering dependencies, query graph for risk-first ordering patterns → aspects/introspection.md § JIT Protocol

• Map dependencies (sequential vs parallel)
• Apply risk-first ordering (riskiest tasks early)
• Maximize parallelism where no mutual dependencies exist
• Verify no circular dependencies

Step 4: Document Plan

Publish work/epics/e{N}-{name}/stories/s{N}.{M}-plan.md via CLI:

Use raise_docs_write MCP tool with doc_type="story-plan", title="S{N}.{M}: {story-name} plan", content="[plan content: overview, ordered task list, execution order, risks, duration tracking table]", output_path="work/epics/e{N}-{name}/stories/s{N}.{M}-plan.md", cwd="{project_or_worktree_path}". If MCP tools are not available, fall back to:

rai docs write story-plan \
  --title "S{N}.{M}: {story-name} plan" \
  --stdin \
  --output-path work/epics/e{N}-{name}/stories/s{N}.{M}-plan.md << 'EOF'
[plan content below]
EOF

Content to include:

• Overview (story ID, size, date)
• Ordered task list with descriptions, files, verification, sizes, dependencies
• Execution order with rationale
• Risks and mitigations
• Duration tracking table (filled during implementation)

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

• NEVER over-decompose simple stories
• NEVER skip TDD guidance — tests define behavior
• NEVER write uv run pytest / npm test in verification — always rai gate check gate-tests --scope
• Gate Policy section included in plan document with concrete --scope paths per task

References

• Gate: gates/gate-plan.md
• Previous: /rai-story-design
• Next: /rai-story-implement