# Epic Journey

> Maps epic touchpoints, emotions, and flow. Use after epic-clarify and any architecture, before wireframes or epic-plan.

- Skill: `telum-ai/epic-journey` (Agent Skill)
- Install (CLI): `npx skillmds@latest add telum-ai/epic-journey`
- Raw SKILL.md: https://api.skillmd.com/api/skills/telum-ai/epic-journey/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: telum-ai (https://skillmd.com/u/telum-ai)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/telum-ai/epic-journey

---



The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).

User input:

$ARGUMENTS

Create a detailed user journey map for an epic to guide design and development decisions.

## Context Gathering

**Required Information:**
1. Project name/ID (ask if not provided)
2. Epic name/ID (ask if not provided)
3. Load: project UX strategy, epic specification

If missing: "Which project and epic should I map the user journey for?"

## Interactive Journey Mapping

### Step 1: Understand Journey Context

**Determine PROJECT_ID** from epic path (e.g., `specs/projects/001-myproject/epics/...`).

**Load required design context**:
- `specs/projects/[PROJECT_ID]/ux-strategy.md` → UX principles, voice/tone, emotional design goals
  - Extract: Design principles, user personas, emotional journey targets, accessibility standards
  - If missing: WARN "No UX strategy found. Run `/project-ux` for UX guidelines that inform journey mapping."

- `specs/projects/[PROJECT_ID]/design-system.md` → Design tokens, interaction patterns
  - Extract: Interaction patterns, feedback mechanisms, animation guidelines
  - If missing: Note that touchpoint design will need alignment later

**Load epic context**:
- Epic specification for scope
- User personas from project spec (referenced in ux-strategy.md)

### Step 2: Journey Discovery

The journey template (`.speck/templates/epic/journey-template.md`) needs specific inputs. Ask for what's missing:

**Core journey questions:**
- "What triggers users to start this journey?"
- "What tells them they've succeeded?"
- "Which persona is this journey for?"

**If stages unclear:**
- "Walk me through the main steps users take..."
- "What are the key decision points?"

**If emotions unknown:**
- "How do users typically feel at the start?"
- "Where might they get frustrated?"
- "What would delight them?"

### Step 3: Pain Point Identification

For each stage identified, explore:
- "What could go wrong here?"
- "What might confuse users?"
- "Where do they typically need help?"

### Step 4: Opportunity Discovery

Based on pain points:
- "How might we reduce this friction?"
- "Where can we exceed expectations?"
- "What would make this memorable?"

### Step 5: Create Journey Map

1. Load template: `.speck/templates/epic/journey-template.md`
2. Create file at: `specs/projects/[PROJECT_ID]/epics/[EPIC_ID]/user-journey.md`
3. Fill systematically:
   - Use discovered stages and emotions
   - Document all pain points
   - Include opportunity areas
   - Add success metrics
   - Mark unclear areas with [NEEDS CLARIFICATION]

### Step 6: Continue

Re-read the canonical flow in root `AGENTS.md` and continue at the next applicable epic slot.

The template contains the complete structure and guidance for journey documentation.