Epics

What is an epic?

An epic is a body of work too large for a single story — typically 3 to 10 stories that together deliver a coherent outcome. While a story is "add user greeting," an epic is "redesign the onboarding experience."

Epics are logical containers, not branches. They have a directory (work/epics/e{N}-{name}/) that holds scope, design, plan, and all story artifacts. Stories branch from your development branch, not from an epic branch.

When to use epics

Situation	Use
One feature, one session	Story
2-3 related changes	Story (larger scope)
3-10 stories toward one goal	Epic
10+ stories	Split into multiple epics

You don't need epics for your first few stories. Start with individual stories to learn the rhythm. Epics become useful once you're comfortable with the story cycle and need to coordinate larger work.

The epic lifecycle

Step	Skill	What happens	Artifact
Start	/rai-epic-start	Create epic directory, write brief and scope	brief.md, scope.md
Design	/rai-epic-design	Gemba walk, decompose into stories, write design	design.md
Plan	/rai-epic-plan	Sequence stories, identify dependencies	plan.md
Work	[story cycle per story]	Execute each story through its full lifecycle	Story artifacts
Close	/rai-epic-close	Epic retrospective, patterns, cleanup	Retrospective

How epics organize work

An epic directory looks like:

work/epics/e16310-onboarding-ux/
├── brief.md              # Hypothesis, success metrics, appetite
├── scope.md              # In/out scope, story list, done criteria
├── design.md             # Gemba findings, approach per story
├── plan.md               # Story sequence, dependencies, risks
└── stories/
    ├── s16311-story.md    # Story 1 artifacts
    ├── s16311-design.md
    ├── s16311-plan.md
    ├── s16311-retrospective.md
    ├── s16319-story.md    # Story 2 artifacts
    └── ...

Each story within an epic follows the full story lifecycle — scope, design, plan, implement, review, close. The epic provides the strategic direction; stories provide the execution.

Key concepts

• Brief — the hypothesis: "If we do X, then Y will improve." Includes success metrics, appetite (how much time we're willing to invest), and rabbit holes (what NOT to build)
• Scope — what's in, what's out, and the done criteria. Updated as stories complete
• Design — gemba walk findings and the approach for each story. This is where you read the actual code before proposing changes
• Plan — story sequencing with dependencies. Which stories can run in parallel? Which must be sequential?

What's next

• Stories — How individual stories within an epic work
• Sessions — How sessions provide context for epic work
• Getting Started — Complete first-use setup