user-story-canvas

User Story Mapper — User Story Map HTML Generator

Organize product requirements by Epic → Feature → Story into a three-tier structure and visualize them as an interactive HTML page, supporting MoSCoW priority color coding + Release swimlane lines.

---

Quick Start

Users only need to provide product requirement information; the Agent is responsible for:

1. Guiding users to sort out the Epic / Feature / Story hierarchy
2. Confirming MoSCoW priorities and Release assignments
3. Building the JSON data and calling the script to generate the HTML
4. Outputting a self-contained HTML file that can be opened directly in a browser

Users only need to say:

"Help me draw a story map. I have 3 Epics, including user registration, product browsing, and order payment"

The Agent will guide the user to complete the entire story map construction step by step.

---

I. Core Concepts

Three-Tier Structure

Level	Meaning	Example
Epic	Large value theme / user activity	User Registration and Login
Feature	Functional modules under an Epic	Phone number registration, email registration, third-party login
Story	Smallest deliverable user story	As a user, I can register with my phone number + verification code

MoSCoW Priority

Level	Meaning	Color
Must	Must have; the product is unusable without it	🔴 Red
Should	Should have; significantly increases value	🟠 Orange
Could	Could have; nice to have	🔵 Blue
Wont	Won't do this time; recorded for reference	⚪ Gray

Release Swimlane Lines

Horizontal divider lines group story cards by version:

• Above the Release 1 (MVP) line = must be delivered in the first version
• Above the Release 2 line = planned for delivery in the second version
• And so on

---

II. Workflow

Step 1: Collect requirement information

Ask the user about the following:

Information Item	Required	Description
Project Name	✅	Displayed in the map title
Epic List	✅	2-8 Epics
Features for each Epic	✅	1-6 Features under each Epic
Stories for each Feature	✅	1-10 Stories under each Feature
Priority for each Story	✅	must / should / could / wont
Release for each Story	✅	Which version it belongs to
Release List	✅	Version names and descriptions
Story Points (optional)	❌	Estimated effort
Story Description (optional)	❌	Additional notes

Step 2: Build the JSON data

Organize the data in the following format:

{
  "project": "电商平台 MVP",
  "releases": [
    {"name": "Release 1", "description": "MVP 核心功能"},
    {"name": "Release 2", "description": "体验优化"},
    {"name": "Release 3", "description": "增长功能"}
  ],
  "epics": [
    {
      "name": "用户系统",
      "features": [
        {
          "name": "注册登录",
          "stories": [
            {
              "name": "手机号注册",
              "priority": "must",
              "release": "Release 1",
              "points": 3,
              "description": "用户可以通过手机号+验证码完成注册"
            },
            {
              "name": "微信登录",
              "priority": "should",
              "release": "Release 2",
              "points": 5
            }
          ]
        }
      ]
    }
  ]
}

Field Description

Field	Type	Required	Description
project	string	✅	Project name
releases	array	✅	Release list (in order)
releases[].name	string	✅	Release name, must match the release field in Story
releases[].description	string	❌	Release description
epics	array	✅	Epic list
epics[].name	string	✅	Epic name
epics[].features	array	✅	Feature list
epics[].features[].name	string	✅	Feature name
epics[].features[].stories	array	✅	Story list
stories[].name	string	✅	Story name
stories[].priority	string	✅	must / should / could / wont
stories[].release	string	✅	Owning release name
stories[].points	number	❌	Story Points
stories[].description	string	❌	Additional description

Step 3: Invoke the script to generate HTML

# 从 JSON 文件生成
python3 scripts/generate_story_map.py --input data.json --output story_map.html

# 从 stdin 读取 JSON
echo '{"project":"demo",...}' | python3 scripts/generate_story_map.py --output story_map.html

Command parameters

Parameter	Required	Description
--input	❌	Input JSON file path (if not provided, read from stdin)
--output	✅	Output HTML file path

Step 4: Deliver the HTML

The script will generate aself-contained HTML file(no external dependencies), with the following features:

• 📊 Epic → Feature → Story three-level card layout
• 🎨 MoSCoW priority color coding
• 📏 Release version grouping with dividing lines
• 📱 Responsive design with horizontal scrolling support
• 🖨️ Print-friendly (automatically adapts to A3 landscape)
• 💡 Hover the mouse to show Story details
• 📈 Statistics panel (Story counts and Points totals by priority/release)

---

III. Guidance Script Reference

Opening

I'll help you build a user story map. Please first tell me:

1. What is the project name?
2. What are the main large functional modules (Epics)?
3. How many releases are planned?

Step-by-step guidance

Okay, let's break down the "{Epic name}" Epic:

• What specific features (Features) does it include?
• What user stories (Stories) are under each feature?

Confirm priorities

Here is the list of stories under "{Feature name}". Please confirm the priority of each:

Story	Suggested priority	Your confirmation
...	Must

Confirm release assignment

Please confirm which Release version each Story belongs to:

• Release 1 (MVP): Core essential features
• Release 2: Experience optimization
• Release 3: Growth features

---

IV. Notes

1. Data validation: The script automatically checks whether the Release name referenced by a Story exists in the releases list
2. Priority validation: priority only accepts the four values must / should / could / wont
3. Empty data handling: If a Feature has no Stories, that column displays a blank placeholder
4. Chinese-English compatibility: Project names, Epic names, etc. support mixed Chinese and English
5. Large map提示: If the total number of Stories exceeds 50, it is recommended to split into multiple sub-maps