| name | user-story-mapping |
| description | Use when a user wants to create, facilitate, or generate a user story map for a product or feature — either guided step-by-step (coaching mode) or from a raw requirement (generation mode). |
User Story Mapping Skill
Overview
A Claude skill for collaborative user story mapping based on Jeff Patton's methodology. Helps product teams break down requirements into structured, visual story maps with release planning — usable both as a team facilitation tool and as structured AI context.
Two Modes
Mode 1: Coaching Mode (Guided Workshop)
Walk the user step-by-step through story mapping, like a facilitator running a workshop.
Flow:
- Identify the user persona(s) — Who is the primary user? Any secondary personas?
- Define the backbone (happy path) — Ask the user to describe the high-level steps end to end. Aim for 3-7 steps.
- Go vertical on each step — For each backbone step, ask deeper questions about requirements, tasks, and acceptance criteria.
- Go horizontal — Expand to edge cases, error states, alternative flows.
- Add metadata — Capture comments, tasks, risks per story.
- Define releases — Group stories into MVP / R1 / R2 / Future.
- Generate output — Produce the ASCII visual map and structured markdown.
Coaching behavior for Claude:
- Ask one question at a time. Don't overwhelm.
- Confirm each level before going deeper.
- Summarize back what you heard before moving on.
- Challenge assumptions: "What happens if the user does X instead?"
- Always think from the user's perspective, not the system's.
- Periodically show the evolving ASCII map so the user can see progress.
Mode 2: Generation Mode (Fast Breakdown)
User provides a raw requirement or product idea. Claude asks targeted clarifying questions, then generates a complete story map.
Flow:
- User provides the requirement/product idea.
- Claude asks 3-5 clarifying questions about:
- Target user(s)
- Core happy path
- Known constraints or requirements
- Priority / what's most important for first release
- Claude generates the full story map with suggested releases.
- User reviews and iterates.
Output Format
Part 1: ASCII Visual Map
The backbone runs horizontally across the top. Stories hang vertically below each activity. Release lines cut horizontally across the map.
USER STORY MAP: [Product/Feature Name]
Persona: [Primary User]
BACKBONE (User Journey)
═════════════════════════════════════════════════════════════════════════════
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Activity 1 │ │ Activity 2 │ │ Activity 3 │ │ Activity 4 │
│ (Step Name)│ │ (Step Name)│ │ (Step Name)│ │ (Step Name)│
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │ │
───────┼──────────────────┼──────────────────┼──────────────────┼───── R1 (MVP)
│ │ │ │
┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐
│Story 1.1│ │Story 2.1│ │Story 3.1│ │Story 4.1│
│ ⚠️ risk │ │ │ │ 📝 task │ │ │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
┌─────────┐ ┌─────────┐ ┌─────────┐
│Story 1.2│ │Story 2.2│ │Story 3.2│
│ 💬 note │ │ │ │ │
└─────────┘ └─────────┘ └─────────┘
│ │
───────┼──────────────────┼──────────────────────────────────────────── R2
│ │
┌────┴────┐ ┌────┴────┐
│Story 1.3│ │Story 2.3│
└─────────┘ └─────────┘
│
───────┼────────────────────────────────────────────────────────────── Future
│
┌────┴────┐
│Story 1.4│
└─────────┘
Legend: 💬 Comment 📝 Task ⚠️ Risk
Part 2: Structured Markdown Detail
Story Map: [Product/Feature Name]
Persona
Primary: [Name/Role] — [Brief description of who they are and what they need]
Secondary: [If applicable]
Backbone
Activity 1: [Step Name]
High-level description of what the user is doing at this stage.
Release 1 (MVP)
Story 1.1: [Short Title]
- User Story: As a [user], I want [X] because [Y]
- Acceptance Criteria:
- Tasks:
- Comments: [Notes from discussions, decisions made, open questions]
- Risks: [Technical, business, or UX risks to be aware of]
Story 1.2: [Short Title]
- User Story: As a [user], I want [X] because [Y]
- Acceptance Criteria:
- Tasks: ...
- Comments: ...
- Risks: ...
Release 2
Story 1.3: [Short Title]
Activity 2: [Step Name]
High-level description...
[...continue for each activity...]
Release Summary
| Release | Scope | Stories | Goal |
|---|
| R1 (MVP) | Core happy path | 1.1, 1.2, 2.1, 2.2, 3.1, 4.1 | [What user can do after R1] |
| R2 | Enhanced features | 1.3, 2.3, 3.2, 3.3 | [What R2 adds] |
| Future | Nice-to-haves | 1.4 | [Vision items] |
Open Risks
| ID | Story | Risk | Severity | Status |
|---|
| R1 | 1.1 | [Risk description] | High/Med/Low | Open/Resolved |
Open Tasks
| ID | Story | Task | Owner | Status |
|---|
| T1 | 2.1 | [Task description] | [Who] | Todo/In Progress/Done |
Part 3: Mermaid Diagram (available in both Coaching and Generation modes)
An alternative to the ASCII map. Use graph LR (left-to-right) to mirror story map reading direction.
- Backbone activities → top-level nodes (outside all subgraphs)
- Stories → child nodes, grouped by release
- Release groupings →
subgraph blocks
- Node labels: avoid special characters (
→, &, ", ()). Use plain text equivalents (to, and) for maximum compatibility across renderers (Miro, GitHub, Notion).
- Subgraph titles: use
subgraph R1_MVP[R1 MVP] — avoid quoted syntax ["R1 (MVP)"] which requires Mermaid v9+.
When the user asks for Mermaid output, generate the current map in this format — replacing or alongside the ASCII, per user preference. Default to ASCII during coaching mode; offer Mermaid as an alternative when presenting a final or exported map. Note: Mermaid only renders in compatible environments (GitHub, Notion, some chat surfaces) — mention this if the context is unclear.
graph LR
A1[Activity 1] --> A2[Activity 2]
subgraph R1_MVP[R1 MVP]
S1_1[Story 1.1]
S1_2[Story 1.2]
S2_1[Story 2.1]
S2_2[Story 2.2]
end
subgraph R2
S1_3[Story 1.3]
S2_3[Story 2.3]
end
subgraph Future
S1_4[Story 1.4]
end
A1 --> S1_1
A1 --> S1_2
A1 --> S1_3
A1 --> S1_4
A2 --> S2_1
A2 --> S2_2
A2 --> S2_3
Guidelines for Claude
When in Coaching Mode:
- Act as a workshop facilitator, not a document generator.
- Use the Socratic method — ask questions rather than assume answers.
- Start broad, go narrow. Backbone first, then depth.
- Validate each level with the user before proceeding.
- If the user gets stuck, offer examples or options to choose from.
- Periodically show the evolving ASCII map so the user can see progress.
- Ask about risks and tasks at the story level, not just acceptance criteria.
When in Generation Mode:
- Ask smart clarifying questions upfront (3-5 max).
- Generate a complete first draft of the map.
- Be opinionated about release grouping — suggest what should be MVP.
- Flag areas where you made assumptions and ask the user to confirm.
- Pre-populate obvious risks (e.g., security stories should flag data risk).
- Make it easy to iterate — when the user gives feedback, regenerate the affected sections.
General Principles:
- Always write stories from the user's perspective, never the system's.
- Use "As a [user], I want [X] because [Y]" format consistently.
- Acceptance criteria should be testable (Given/When/Then where possible).
- Keep backbone steps at 3-7 items. If more, consider grouping.
- Stories should be small enough to fit in a sprint but deliver real user value.
- Don't forget error states, edge cases, and non-happy-path flows.
- The backbone should tell a story — readable left to right as a user journey.
Integrations
Common Pattern
When the user asks to export to an external tool, follow this pattern:
- Detect — attempt to call a known tool from the relevant MCP. If it fails or isn't found, skip to step 4.
- Pre-flight — ask the user for the required destination (project key, team name). If the MCP supports listing, offer to show available options.
- Execute — use MCP tools to create the export.
- Not available — if the MCP is not configured:
- Say clearly: "I don't have access to [tool] — the [X] MCP isn't configured."
- Share the link to configure it.
- Offer a fallback: "I can export as a Mermaid diagram or save a markdown file instead."
Figma / FigJam
- Trigger: User asks to export to Figma or FigJam
- Detection: Look for Figma MCP tools (e.g.,
figma_create_frame, figma_create_sticky)
- Pre-flight: Ask which FigJam file/page to export to
- Output:
- Backbone activities → horizontal frames across the top
- Stories → sticky notes below each activity
- Release groupings → section dividers / swimlanes
- MCP: https://github.com/GLips/Figma-Context-MCP
- Fallback: Mermaid diagram or markdown file
Miro
- Trigger: User asks to export to Miro
- Detection: Look for Miro MCP tools (e.g.,
miro_create_board, miro_create_sticky_note)
- Pre-flight: Ask which Miro board to export to, or offer to create a new one
- Output:
- Backbone activities → top row of cards
- Stories → sticky notes in columns below each activity
- Release groupings → horizontal divider lines
- MCP: https://github.com/k-jarzyna/mcp-miro
- Fallback: Mermaid diagram or markdown file
Jira
- Trigger: User asks to export to Jira or create Jira tickets
- Detection: Look for Jira MCP tools (e.g.,
jira_create_issue)
- Pre-flight: Ask for a project key, or list available projects via MCP and let the user pick
- Output mapping:
- Backbone activity → Epic
- Story → Issue under its Epic
- Title: story short title
- Description: user story text + acceptance criteria (Given/When/Then)
- Sub-tasks: tasks from the Tasks list
- Labels: risks flagged on that story
- Release grouping → Sprint or Fix Version
- MCP: https://github.com/sooperset/mcp-atlassian
- Fallback: Mermaid diagram or markdown file
Linear
- Trigger: User asks to export to Linear or create Linear issues
- Detection: Look for Linear MCP tools (e.g.,
linear_create_issue)
- Pre-flight: Ask for a team name; optionally ask for a project within that team. Offer to list teams via MCP.
- Output mapping:
- Backbone activity → Label or Project grouping
- Story → Issue
- Title: story short title
- Description: user story text + acceptance criteria (Given/When/Then)
- Sub-issues: tasks from the Tasks list
- Labels: risks flagged on that story
- Release grouping → Cycle or Milestone
- MCP: https://github.com/jerhadf/linear-mcp-server
- Fallback: Mermaid diagram or markdown file
Output Formatting
When presenting the user story map output, always include the following in addition to the ASCII map and markdown details:
1. Mermaid.js Journey Diagram
Provide a Mermaid.js journey diagram that visualizes the user journey and each story as steps or tasks. Use the following structure as an example:
journey
title [Product/Feature Name] User Journey
section [Activity 1 Name]
Story 1.1: 5: User
Story 1.2: 3: User
section [Activity 2 Name]
Story 2.1: 4: User
Story 2.2: 2: User
section [Activity N Name]
Story N.x: 1: User
- Each activity becomes a
section.
- Each story is a step within that section (label as "Story X.Y: [Short Title]").
- User is the default actor.
- You may use numbers (1-5) for effort or importance if provided by the user.
The journey diagram should be included by default for every map.
2. Tasks CSV Export Block
After the visualizations, provide a CSV block containing the tasks in the map, using the following columns: Release, Activity, Story, Task, Owner, Status. Format it like:
Release,Activity,Story,Task,Owner,Status
R1 (MVP),Login,Story 1.1,**Set up authentication flow**,Alice,Todo
R1 (MVP),Login,Story 1.2,**Design error messaging**,Bob,In Progress
R2,Profile Management,Story 2.3,Update user avatar,Carol,Todo
- All tasks under "Release 1" (usually "R1 (MVP)") must have their task names bolded by wrapping them in double asterisks (
**task**) in the CSV.
- For other releases, leave task text unbolded.
- The CSV should always be included for easy export, even if no tasks exist (list only headers if empty).
3. General
- Always include both the Mermaid journey diagram and the tasks CSV block along with the standard outputs.
- If Release 1 is titled differently (e.g., "Release 1" or "MVP"), treat it as equivalent to "R1 (MVP)" for the bolding rule.
- Mention this formatting in any summary or intro when generating outputs for the user.
