RE
User Story Mapping
Requirements core v1.0.0
User Story Mapping
Overview
User story mapping is the technique of decomposing requirements into a hierarchical structure of Epics → User Stories → Tasks, organized around user personas and workflows. In the full-lifecycle pipeline, story mapping transforms raw requirements into prioritized, implementable work items that drive architecture, API design, and implementation phases.
Key Concepts
Story Hierarchy
┌─────────────────────────────────────────────────────────────┐
│ Story Hierarchy │
├─────────────────────────────────────────────────────────────┤
│ │
│ THEME (Strategic Goal) │
│ └── EPIC (Large Feature Area) │
│ └── USER STORY (Single User Capability) │
│ └── TASK (Implementation Unit) │
│ │
│ Example: │
│ Theme: "Self-Service Customer Support" │
│ ├── Epic: "Ticket Management" │
│ │ ├── Story: "Submit a ticket" │
│ │ │ ├── Task: Create ticket API endpoint │
│ │ │ ├── Task: Build ticket form component │
│ │ │ └── Task: Add ticket table migration │
│ │ ├── Story: "View ticket status" │
│ │ └── Story: "Update ticket" │
│ └── Epic: "Knowledge Base" │
│ ├── Story: "Search articles" │
│ └── Story: "View article" │
│ │
└─────────────────────────────────────────────────────────────┘
User Story Format
As a [persona],
I want [action/capability],
So that [benefit/value].
INVEST Criteria
| Criterion | Definition | Validation Question |
|---|---|---|
| Independent | No dependencies on other stories | Can this be built and delivered alone? |
| Negotiable | Details can be discussed | Is the implementation open to discussion? |
| Valuable | Delivers value to a user or stakeholder | Does someone benefit when this is done? |
| Estimable | Team can estimate effort | Is the scope clear enough to size? |
| Small | Fits within a sprint | Can this be completed in 1-5 days? |
| Testable | Has clear acceptance criteria | Can we write a test for this? |
Persona Identification
┌─────────────────────────────────────────────────────────────┐
│ Persona Template │
├─────────────────────────────────────────────────────────────┤
│ │
│ Name: [Role Name] │
│ Description: [Who they are] │
│ Goals: [What they want to achieve] │
│ Pain Points: [Current frustrations] │
│ Technical Level: [Novice | Intermediate | Expert] │
│ Frequency: [Daily | Weekly | Monthly | Occasional] │
│ │
│ Example: │
│ Name: Customer │
│ Description: End user seeking support │
│ Goals: Resolve issues quickly, find answers independently │
│ Pain Points: Long wait times, repetitive explanations │
│ Technical Level: Novice │
│ Frequency: Occasional │
│ │
└─────────────────────────────────────────────────────────────┘
Best Practices
- Start with personas — Identify all user roles before writing stories
- Map the user journey — Walk through complete workflows, then decompose
- One story = one capability — If it has “and”, split it
- Size stories to 1-5 days — Larger items are epics, split further
- Tag stories by layer —
[backend],[frontend],[database],[ai]for pipeline routing - Assign MoSCoW priority to every story — drives MVP vs future phase
- Cross-reference dependencies —
dependsOn: [US-003]for sequencing
Code Examples
✅ Good: Well-Decomposed Epic
epic:
id: E-001
title: "Ticket Management"
description: "Complete ticket lifecycle from submission to resolution"
priority: MUST
stories:
- id: US-001
title: "Submit Support Ticket"
persona: "Customer"
narrative: "As a customer, I want to submit a support ticket, so that I can report my issue"
acceptanceCriteria:
- "Given I am logged in, When I fill title, description, priority and submit, Then a ticket is created with status OPEN"
- "Given I submit a ticket, When validation fails, Then I see field-level error messages"
estimatedComplexity: MEDIUM
tags: [backend, frontend, database]
dependsOn: []
- id: US-002
title: "View My Tickets"
persona: "Customer"
narrative: "As a customer, I want to view my submitted tickets, so that I can track their status"
acceptanceCriteria:
- "Given I have submitted tickets, When I visit my tickets page, Then I see a list sorted by last updated"
- "Given I have no tickets, When I visit my tickets page, Then I see an empty state with a create button"
estimatedComplexity: LOW
tags: [backend, frontend]
dependsOn: [US-001]
❌ Bad: Poorly Written Stories
# Too vague — not testable
- title: "Manage tickets"
narrative: "As a user, I want ticket management"
# Missing: specific action, specific persona, acceptance criteria
# Too large — should be split
- title: "Users can submit, view, update, and delete tickets and comments"
# This is an epic, not a story — has multiple capabilities
# No value — implementation detail, not user value
- title: "Create tickets table in PostgreSQL"
# This is a task, not a story
Anti-Patterns
- Technical Stories — “As a developer, I want the database indexed” (implementation task, not user story)
- Compound Stories — Stories with “and” that should be split into separate stories
- Missing Personas — Generic “As a user” without identifying specific roles
- No Acceptance Criteria — Stories without testable conditions
- Orphan Stories — Stories not connected to any epic or theme
- Dependency Chains — Long chains of dependent stories that prevent parallel work
Testing Strategies
- Story Review — Each story passes INVEST criteria checklist
- Acceptance Test Derivation — Each AC generates at least one automated test
- Persona Coverage — All identified personas have stories
- Priority Coverage — MUST stories form a viable MVP