rai-epic-design-enterprise

Epic Design

Purpose

Design an epic that bridges strategic objectives to executable stories, making key architectural decisions and defining bounded scope for incremental delivery.

Mastery Levels (ShuHaRi)

• Shu: Follow all steps, create full scope document and ADRs
• Ha/Ri: Adjust depth based on complexity, lightweight ADRs, custom patterns

Context

When to use: Starting work spanning 3-10 stories. Design is the gemba walk at epic scale — go see what exists, challenge assumptions, prevent waste.

When to skip: Single-story work → /rai-story-design. Bug fixes → issue tracker. High uncertainty → /rai-research first.

Inputs: Business objective, project backlog, constraints. Optionally: Problem Brief from /rai-problem-shape or Epic Brief from /rai-epic-start.

Steps

PRIME (mandatory — do not skip)

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

1. Chain read: No chain read — epic-design is the first skill in the epic chain.
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.
5. Backlog transition — engine owned (RAISE-15034): Transition to design status is performed by the pipeline engine via apply_phase_transition. No skill-initiated transition call required or allowed.

Step 1: Load Brief & Frame Objective

Check for Epic Brief (work/epics/e{N}-{name}/brief.md) or Problem Brief (work/problem-briefs/*.md). If found, use hypothesis and boundaries as starting input.

Define what this epic accomplishes:

• Objective: Business/user outcome (1-2 sentences, outcome-focused)
• Value: Why this matters, what's unlocked after completion
• In scope (MUST/SHOULD): Non-negotiable vs nice-to-have deliverables
• Out of scope: Excluded items with rationale and deferral destination

Scoping heuristic: defer what doesn't block the objective; separate what needs its own ADRs.

JIT: Before defining scope boundaries, query graph for prior designs with similar scope → aspects/introspection.md § JIT Protocol

Step 2: Gemba Walk (mandatory — do not skip)

Go to the actual codebase. Read what exists before designing what's next.

1. Read the modules this epic will touch. Understand current state, not just the graph abstraction.

Module Health Check — before proposing stories, check if any touched module is a known drift hotspot:

# Replace MOD_TOKEN with module name fragments (e.g. "auth", "pipeline", "graph")
cat governance/drift-hotspots.json 2>/dev/null | python3 -c "
import json, sys
MOD_TOKENS = ['MOD_TOKEN']  # replace with actual module name fragments
data = json.load(sys.stdin)
hits = [m for m in data.get('ranked_modules', []) if any(t in m.get('id', '') for t in MOD_TOKENS)]
for m in hits[:5]: print(f'{m[\"id\"]}: rank {m[\"rank\"]}, signals {m[\"signal_count\"]}')
" 2>/dev/null || echo "(hotspots.json not available — skip)"

If a module appears in the top-10 ranked list: flag it in this epic's scope.md §Risks section with the signal count. See governance/drift-catalog.md for signal definitions. Graceful degradation: if hotspots.json is absent, skip silently.

2. Search for existing implementations: grep for similar functionality, patterns, components. Before proposing new stories, verify they won't duplicate what exists.
3. Check established patterns: how does the codebase already solve similar problems? Follow existing patterns rather than inventing new ones.
4. Map the real dependencies: what actually imports what? What breaks if you change X?

Use raise_graph_context MCP tool with module_id="mod-{name}", cwd="{project_or_worktree_path}". If MCP tools are not available, fall back to: rai graph context mod-{name} --format json

grep -r "similar_pattern" packages/  # real code

Step 3: Assess Architecture & ADRs

Create ADRs when: multiple valid approaches with significant impact, new technology adoption, decisions other epics depend on. Skip when patterns are established or details are easily changed.

JIT: Before making architectural decisions, query graph for patterns and known risks → aspects/introspection.md § JIT Protocol

If significant uncertainty: /rai-research (timebox 2-4 hours), then create ADRs. ADR template: .raise/templates/architecture/adr.md. One decision per ADR.

Publish each ADR to local path and docs adapter:

Use raise_docs_write MCP tool with doc_type="adr", title="ADR-YYYY-MM-DD-{slug}: {Decision Title}", content="[ADR content following .raise/templates/architecture/adr.md structure]", output_path="governance/adrs/adr-YYYY-MM-DD-{slug}.md", cwd="{project_or_worktree_path}". Verify result: If result.status != "ok", stop immediately with error: ADR write failed: {result.error}. Cannot continue without docs sync in connected mode. If MCP tools are not available, fall back to:

rai docs write adr \
  --title "ADR-{NNN}: {Decision Title}" \
  --stdin \
  --output-path governance/adrs/adr-YYYY-MM-DD-{slug}.md << 'EOF'
[ADR content following .raise/templates/architecture/adr.md structure]
EOF

If exit code != 0, stop immediately — do not proceed to scope creation.

Capability-registry check (RAISE-14654): if the ADR names a canonical, single-implementation mechanism (a function/service/endpoint that all callers must use — the same shape as an existing governance/capability-registry.yaml card), add or update that card in the same MR. This is how a decision becomes discoverable at design time instead of only living in ADR prose — the root cause found in RAISE-14654 was ADRs naming canonical mechanisms that never got promoted into the registry. Skip silently when the ADR doesn't name such a mechanism (most don't).

Step 4: Break Down Stories (MVP mentality)

Decompose epic into 3-10 independently deliverable stories. Apply lean principles:

• KISS: Each story does one thing well. If explanation takes >2 sentences, split it.
• YAGNI: Only stories that serve the stated objective. "Nice to have" goes to parking lot.
• DRY: Check gemba findings — if a story duplicates existing functionality, remove or reframe as extension.
• Everything is an MVP: Each story delivers the simplest version that proves value. Gold-plating goes to follow-up epics.

Per story: ID (S{N}.{seq}), name, 1-line description, T-shirt size (XS/S/M/L), dependencies.

JIT: Before finalizing decomposition, query graph for sizing patterns in similar epics → aspects/introspection.md § JIT Protocol

Target: each story delivers demonstrable value, 1-5 days duration. No dependency cycles. External blockers identified.

Waste check: For each proposed story, ask: "What happens if we don't build this?" If the epic still achieves its objective, the story is not essential — defer it.

Step 5: Define Done & Risks

Done: All stories complete + epic-specific measurable criteria + architecture docs updated + retrospective completed.

Risks: Top 3 with likelihood/impact/mitigation.

JIT: Before assessing risks, query graph for known risks from related epics → aspects/introspection.md § JIT Protocol

Step 6: Write Artifacts & Parking Lot

Create TWO documents via CLI:

1. scope.md (WHAT + WHY): objective, stories, boundaries, done criteria:

Use raise_docs_write MCP tool with doc_type="epic-scope", title="E{N}: {epic-name} scope", content="[scope content following templates/scope.md]", output_path="work/epics/e{N}-{name}/scope.md", cwd="{project_or_worktree_path}". Verify result: If result.status != "ok", stop immediately with error: Epic scope write failed: {result.error}. Cannot continue without docs sync in connected mode. If MCP tools are not available, fall back to:

rai docs write epic-scope \
  --title "E{N}: {epic-name} scope" \
  --stdin \
  --output-path work/epics/e{N}-{name}/scope.md << 'EOF'
[scope content following templates/scope.md]
EOF

If exit code != 0, stop immediately — do not proceed to design creation.

2. design.md (HOW): gemba findings, target components, key contracts:

Use raise_docs_write MCP tool with doc_type="epic-design", title="E{N}: {epic-name} design", content="[design content following templates/design.md]", output_path="work/epics/e{N}-{name}/design.md", cwd="{project_or_worktree_path}". Verify result: If result.status != "ok", stop immediately with error: Epic design write failed: {result.error}. Cannot continue without docs sync in connected mode. If MCP tools are not available, fall back to:

rai docs write epic-design \
  --title "E{N}: {epic-name} design" \
  --stdin \
  --output-path work/epics/e{N}-{name}/design.md << 'EOF'
[design content following templates/design.md]
EOF

If exit code != 0, stop immediately — do not proceed to Jira update.

Both documents are required. For simple epics, design.md is short (gemba findings + approach), not absent.

3. Update Jira description with the full scope (replaces the 1-line set at creation time):

Use the raise_backlog_update MCP tool with issue_key="{JIRA_KEY}", custom_fields='{"description": "{objective 1-2 sentences}\n\nStories: {S{N}.1 — title} | {S{N}.2 — title} | {S{N}.3 — title}\n\nDone when: {key done criteria — comma-separated}"}'. If MCP tools are not available, fall back to:

rai backlog update {JIRA_KEY} \
  -F "description={objective 1-2 sentences}

Stories: {S{N}.1 — title} | {S{N}.2 — title} | {S{N}.3 — title}

Done when: {key done criteria — comma-separated}"

Capture deferred items in dev/parking-lot.md (Edit tool) with origin, priority, and promotion conditions.

Output

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

Quality Checklist

• Epic Brief consumed as input (if exists from /rai-epic-start)
• Gemba walk done — actual code read, no duplicate components proposed
• Objective is outcome-focused, not implementation-focused
• Scope boundaries explicit (in/out documented)
• Lean principles applied: KISS, DRY, YAGNI, MVP mentality
• Waste check: every story is essential for the objective
• Stories independently deliverable (3-10 range)
• Dependencies mapped with no cycles
• Done criteria are measurable
• Both scope.md and design.md produced (design.md is never optional)
• NEVER time-box epics — scope-based, not duration-based
• NEVER over-specify stories — save details for /rai-story-design

References

• Brief template: rai-epic-start/templates/brief.md
• Scope template: templates/scope.md
• Design template: templates/design.md
• ADR template: .raise/templates/architecture/adr.md
• Next: /rai-epic-ux-design (it may hand off directly to /rai-epic-plan when interaction design is not needed)
• Story design: /rai-story-design
• Close: /rai-epic-close