Rai Epic Run

Epic Run

Purpose

Execute the epic lifecycle phases (start → design → AR → plan → close), pausing at delegation gates and at story iteration for human-driven /rai-story-run execution. Resumes automatically from the last completed phase.

Mastery Levels (ShuHaRi)

• Shu: Show phase progress, explain each skill's output, pause at both gates
• Ha: Brief progress between phases, pause only when delegation says REVIEW
• Ri: Minimal output, AUTO delegation, gates stop only on failure

Context

When to use: Starting or resuming any epic. Replaces manual sequential skill and story invocation.

When to skip: Single-phase work (e.g., only closing an already-completed epic). Individual skills remain independently invocable.

Steps

Step 0: Detect Phase

Resolve the epic path from epic_id. Check artifacts in reverse order — take the most advanced phase:

Present: "Phase detection: resuming at {phase}" with context (e.g., "3/5 stories done, 2 remaining").

Step 1: Resolve Delegation

Load developer profile from ~/.rai/developer.yaml. Resolve delegation level:

Present: "Delegation: {level}"

Step 2: Execute Epic Skill Chain

Run each epic skill from the detected phase forward. Show ── Phase {N}/6: {skill_name} ── between phases.

Full execution rule: For each phase, you MUST:

1. Load the skill's SKILL.md (read the file, don't rely on memory)
2. Execute every step in the skill's SKILL.md sequentially — no compression, no skipping
3. Produce all artifacts the skill specifies
4. Only then move to the next phase

The orchestrator delegates — it does not summarize, compress, or shortcut individual skill behavior. A skill invoked through the orchestrator must produce the same output as when invoked standalone.

Step 3: Hand Off Stories

When reaching phase 5 (story iteration), read the ### Progress Tracking table from scope.md:

1. Parse rows — columns: Story, Size, Status, Actual, Velocity, Notes
2. Filter rows where Status != "Done"
3. Present in table order (plan already resolved dependencies)

Quality rule — epic-run NEVER executes story-run. Each /rai-story-run must run in a fresh session/context so it can fork its heavy phases via Agent tool with full context budget. Running story-run inside epic-run would accumulate context across stories, degrading quality in later stories — the exact problem Checkpoint & Fork (ADR-043) was designed to eliminate. We never operate at known lower quality levels.

Present the pending stories and STOP:

## Stories Ready for Execution

| # | Story | Size | Status |
|:-:|-------|:----:|--------|
| 1 | S{N}.1 — {name} | S | Pending |
| 2 | S{N}.2 — {name} | M | Pending |

**Next:** Run each story independently with `/rai-story-run {story_id}`
**Resume:** Re-invoke `/rai-epic-run {epic_id}` when all stories are Done → resumes at close

STOP here. Do not proceed to phase 6. Do not invoke story-run. The developer runs each story in a separate session with fresh context. When all stories are Done, re-invoking /rai-epic-run detects phase=close and proceeds.

Step 4: Apply Delegation Gates

After phase 2 (design), phase 3 (AR), and phase 4 (plan), apply the delegation gate:

Post-design summary: Story count, sizes, key architectural decisions. Post-AR summary: Verdict (PASS/PASS WITH QUESTIONS/SIMPLIFY), proportionality findings, systemic heuristics (H13-H16). Post-plan summary: Milestones, story sequence, estimated timeline.

If AR verdict is SIMPLIFY, STOP regardless of delegation level. Design must be revised before planning.

Story iteration is a mandatory STOP — stories run in separate sessions (see Step 3).

Step 5: Complete & Report

After all phases, present summary: phases executed, stories completed/total, delegation level, merge target. Confirm epic merged and branch cleaned up.

Output

Quality Checklist

• Phase detection checked in reverse order (most advanced first)
• ### Progress Tracking heading used as plan presence marker
• Story iteration filters Status != "Done" (handles spikes naturally)
• Each skill's SKILL.md was loaded (read from file) before execution
• Every step in each skill executed — no compression or shortcuts
• Gates applied at post-design, post-AR, and post-plan
• Failure stops immediately — no cascading
• NEVER create a state file — phase detection is git-derived only
• NEVER skip stories or reorder them — table order is plan order
• NEVER compress a skill's steps into a summary — execute each step fully
• NEVER invoke story-run from epic-run — present list and STOP (ADR-043 quality rule)
• Stories run in separate sessions with fresh context

References

• Epic skills: /rai-epic-start, /rai-epic-design, /rai-architecture-review, /rai-epic-plan, /rai-epic-close
• Story orchestrator: /rai-story-run (S325.6)
• Delegation: ~/.rai/developer.yaml, S325.2
• BacklogHook: S325.4 (fires on rai signal emit-work in start/close)
• Design: s325.7-design.md (decisions D1-D2-D3-D4)
• F5 constraint & checkpoint protocol: E353 (ADR-043), S353.2, S353.3