Rai Story Run

Story Run

Purpose

Execute the full story lifecycle in one invocation, pausing only at delegation gates and resuming 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 story. Replaces manual sequential skill invocation.

When to skip: Single-phase work (e.g., only running review on an already-implemented story). Individual skills remain independently invocable.

Steps

Step 0: Detect Phase

Resolve the epic and story paths from story_id. Check artifacts in reverse order — take the most advanced phase:

Present: "Phase detection: resuming at {phase} (found: {artifact})" or "Starting fresh — no artifacts found."

Step 1: Resolve Delegation

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

Present: "Delegation: {level}"

Step 2: Execute Skill Chain

Run each skill from the detected phase forward.

Phase banner (before starting):

── Phase {N}/8: {skill_name} ──

Completion banner (after finishing each phase):

Use a markdown heading + table so that file paths are clickable in the terminal:

### ✔ Phase {N}/8 — {skill_name}

| | File | Status |
|---|---|---|
| + | `path/to/new-file.md` | created |
| ~ | `path/to/modified-file.py` | modified |

**Commits:** 1 (`abc1234`) · **Tests:** 3463 passed

Rules for the completion banner:

• Use markdown table (NOT ASCII box-drawing) so file paths are clickable
• File paths in backticks, relative to project root
• + for created, ~ for modified, - for deleted
• Only list files the skill actually touched (not inherited from prior phases)
• Commits and tests on a single summary line below the table
• For gate phases (design, implement, AR, QR), add verdict/summary on a separate line
• If phase produced no file changes (e.g., close is just merge), show merge commit hash instead of file table

Chain order:

All phases fork. The orchestrator is a pure coordinator — it never executes skill logic directly. This keeps the terminal output clean (subagent output is contained) and the orchestrator context minimal.

Fork phases (all 8)

Each fork phase runs in a fresh-context subagent via the Agent tool. This eliminates context saturation that degrades quality in later phases.

For each fork phase:

1. Read the skill's SKILL.md from src/raise_cli/skills_base/rai-{skill-name}/SKILL.md
2. Spawn an Agent tool subagent with:
   • subagent_type: "general-purpose"
   • prompt: the agent prompt template below, filled with skill content and story context
3. Wait for agent completion
4. Verify output:
   • Artifact-producing phases (start, design, plan, implement, review): confirm file exists on disk
   • Verdict phases (AR, QR): read verdict from agent return value
   • Close: confirm merge commit from agent return value
5. Show completion banner in main thread
6. Apply delegation gate if applicable (in main thread)

Agent prompt template:

Execute the following skill for story {story_id}.

## Skill Instructions

{paste the full SKILL.md content here}

## Story Context

- Story ID: {story_id}
- Epic: {epic_id}
- Epic path: work/epics/{epic_slug}/
- Stories path: work/epics/{epic_slug}/stories/
- Prior artifacts on disk: {list each file that exists for this story, e.g. s353.2-story.md, s353.2-design.md}

## Your Task

1. Read CLAUDE.md for project-level context and rules
2. Read the prior artifacts listed above from disk
3. Execute every step in the Skill Instructions — no compression, no skipping
4. Write all output artifacts to the correct paths
5. When done, return a brief summary: what you did, artifacts created, and any verdicts or decisions

ARGUMENTS: {story_id}

Critical rules for fork execution:

• The subagent gets the SKILL.md as its prompt — it executes the full skill naturally in fresh context
• Do NOT pass conversation history or prior phase results to the subagent — only disk artifacts and SKILL.md
• The orchestrator stays thin — it only reads summaries and checks for artifacts between forks
• A skill invoked through fork must produce the same output as when invoked standalone

Step 3: Apply Delegation Gates

After phase 2 (design), phase 4 (implement), phase 5 (AR), and phase 6 (QR), apply the delegation gate:

Post-design summary: Approach, components affected, key decisions. Post-implement summary: Tasks completed, tests passing, files changed. Post-AR summary: Verdict (PASS/PASS WITH QUESTIONS/SIMPLIFY), findings count, key heuristics triggered. Post-QR summary: Verdict (PASS/PASS WITH RECOMMENDATIONS/FAIL), findings count, fixes applied.

If AR verdict is SIMPLIFY or QR verdict is FAIL, STOP regardless of delegation level. Fixes must be applied before proceeding.

Step 4: Complete & Report

After all phases complete, present:

## Story Run Complete: {story_id}

**Phases:** {start_phase} → close ({N} phases executed)
**Delegation:** {level}
**Result:** Merged to `{parent_branch}` (`{merge_commit_hash}`)

### Artifacts
| Phase | File | Op |
|-------|------|:--:|
| start | `work/epics/.../stories/s{N}.{M}-story.md` | + |
| start | `work/epics/.../stories/s{N}.{M}-scope.md` | + |
| design | `work/epics/.../stories/s{N}.{M}-design.md` | + |
| plan | `work/epics/.../stories/s{N}.{M}-plan.md` | + |
| implement | `src/path/to/file.py` | ~ |
| implement | `tests/path/to/test.py` | ~ |
| review | `work/epics/.../stories/s{N}.{M}-retrospective.md` | + |

### Metrics
| Metric | Value |
|--------|-------|
| Tests | {count} passed |
| Commits | {total_count} across {phases_count} phases |
| Patterns | {PAT-IDs or "none"} |
| Jira | {ticket} → {status} |

File paths MUST use backticks so they are clickable in the terminal. Use actual paths, not placeholders — the table above is a template.

Output

Quality Checklist

• Phase detection checked in reverse order (most advanced first)
• Delegation resolved from profile before starting chain
• All 8 phases spawn Agent tool subagent with full SKILL.md as prompt
• Each subagent gets fresh context — no conversation history passed
• Artifact-producing forks verified by checking file on disk
• AR/QR verdicts read from agent return value
• Gates applied at post-design, post-implement, post-AR, and post-QR (in main thread)
• Failure stops immediately — no cascading to next phase
• NEVER create a state file — phase detection is git-derived only
• NEVER skip a skill in the chain (even if developer says "just close it")
• NEVER pass conversation context to forked subagent — only disk artifacts + SKILL.md

References

• Skills: /rai-story-start, /rai-story-design, /rai-story-plan, /rai-story-implement, /rai-architecture-review, /rai-quality-review, /rai-story-review, /rai-story-close
• Delegation: ~/.rai/developer.yaml, S325.2
• BacklogHook: S325.4 (fires on rai signal emit-work in start/close)
• Design: s325.6-design.md (decisions D1-D2-D3)