Back to Details

create-user-stories

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create User Stories

创建用户故事

Overview

概述

Generate a user story map following Jeff Patton's story mapping approach, with BDD-style Given/When/Then acceptance criteria for every story. Stories are grouped by user activity, tagged with priority and complexity, and include dedicated edge-case stories.
按照Jeff Patton的故事映射方法生成用户故事地图，为每个故事提供BDD风格的Given/When/Then验收标准。故事按用户活动分组，标记优先级和复杂度，并包含专门的边缘场景故事。

Workflow

工作流程

  1. Read product context — Load 
    .chalk/docs/product/0_product_profile.md
    and any JTBD docs to understand personas, goals, and existing terminology. If no product context exists, work from what the user provides.
  2. Locate the PRD — If 
    $ARGUMENTS
    references a PRD (by path or name), read it. Search 
    .chalk/docs/product/
    for PRD files matching the feature. If a PRD exists, it is the primary input. If no PRD exists, accept the feature description from 
    $ARGUMENTS
    directly and note that stories are being written without a PRD.
  3. Identify user activities — Break the feature into 3-7 high-level user activities (the "backbone" in story mapping). Each activity represents a distinct thing the user does to accomplish their goal. Activities are ordered left-to-right by the sequence the user would perform them.
  4. Write stories for each activity — Under each activity, write stories from highest to lowest priority. Each story gets:
    • The story statement: "As a [persona], I want [action], so that [outcome]"
    • 2-4 acceptance criteria in Given/When/Then format
    • A priority tag: must (MVP), should (important but not blocking), could (nice-to-have)
    • A complexity tag: S (< 1 day), M (1-3 days), L (3-5 days)
  5. Generate edge-case stories — For every activity, add at least one story covering:
    • Error states (what happens when things go wrong)
    • Empty states (first-time use, no data available)
    • Boundary conditions (max limits, large inputs, concurrent access)
    • Permission boundaries (unauthorized user, expired session, role restrictions)
  6. Determine the next file number — Read filenames in 
    .chalk/docs/product/
    to find the highest numbered file. The next number is 
    highest + 1
    .
  7. Write the file — Save to 
    .chalk/docs/product/<n>_user_stories_<feature_slug>.md
    .
  8. Confirm — Tell the user the stories were created, share the file path, total story count, and the must/should/could breakdown.
  1. 读取产品上下文 — 加载
    .chalk/docs/product/0_product_profile.md
    和任何JTBD文档，以了解用户角色、目标和现有术语。如果没有产品上下文，则根据用户提供的内容进行工作。
  2. 定位PRD — 如果
    $ARGUMENTS
    引用了PRD（通过路径或名称），则读取该文件。在
    .chalk/docs/product/
    中搜索与功能匹配的PRD文件。如果存在PRD，则将其作为主要输入。如果没有PRD，则直接接受
    $ARGUMENTS
    中的功能描述，并注明故事是在没有PRD的情况下撰写的。
  3. 识别用户活动 — 将功能拆分为3-7个高级用户活动（故事映射中的“主干”）。每个活动代表用户为实现目标所执行的一项独立操作。活动按用户执行的顺序从左到右排列。
  4. 为每个活动撰写故事 — 在每个活动下，按优先级从高到低撰写故事。每个故事包含：
    • 故事陈述：“作为[用户角色]，我想要[操作]，以便[成果]”
    • 2-4条Given/When/Then格式的验收标准
    • 优先级标签：must（MVP）、should（重要但不阻塞）、could（锦上添花）
    • 复杂度标签：S（<1天）、M（1-3天）、L（3-5天）
  5. 生成边缘场景故事 — 为每个活动添加至少一个涵盖以下内容的故事：
    • 错误状态（出现问题时的情况）
    • 空状态（首次使用、无可用数据）
    • 边界条件（最大限制、大量输入、并发访问）
    • 权限边界（未授权用户、过期会话、角色限制）
  6. 确定下一个文件编号 — 读取
    .chalk/docs/product/
    中的文件名，找到编号最高的文件。下一个编号为
    最高编号 + 1
    。
  7. 写入文件 — 保存到
    .chalk/docs/product/<n>_user_stories_<feature_slug>.md
    。
  8. 确认 — 告知用户故事已创建，共享文件路径、故事总数以及must/should/could的分类统计。

Story Map Structure

故事地图结构

markdown
undefined
markdown
undefined

User Stories: <Feature Name>

User Stories: <Feature Name>

Last updated: <YYYY-MM-DD> (Initial draft)
Source PRD: <PRD title> (or "None — stories written from feature description")
Last updated: <YYYY-MM-DD> (Initial draft)
Source PRD: <PRD title> (or "None — stories written from feature description")

Story Map Overview

Story Map Overview

ActivityMustShouldCouldTotal
<activity 1>XYZN
<activity 2>XYZN
TotalXYZN
ActivityMustShouldCouldTotal
<activity 1>XYZN
<activity 2>XYZN
TotalXYZN

Activity 1: <Activity Name>

Activity 1: <Activity Name>

<1-sentence description of what the user is doing and why>
<1-sentence description of what the user is doing and why>

Story 1.1: <Short story title>

Story 1.1: <Short story title>

Priority: must | Complexity: S/M/L
As a [persona], I want [action], so that [outcome].
Acceptance Criteria:
  • Given [context], when [action], then [expected result]
  • Given [context], when [action], then [expected result]
  • Given [context], when [action], then [expected result]
Priority: must | Complexity: S/M/L
As a [persona], I want [action], so that [outcome].
Acceptance Criteria:
  • Given [context], when [action], then [expected result]
  • Given [context], when [action], then [expected result]
  • Given [context], when [action], then [expected result]

Story 1.2: <Short story title>

Story 1.2: <Short story title>

...
...

Story 1.E1: <Edge case title>

Story 1.E1: <Edge case title>

Priority: must | Complexity: S/M/L Edge case type: error state | empty state | boundary | permission
As a [persona], I want [behavior when X goes wrong], so that [I can recover / understand what happened].
Acceptance Criteria:
  • Given [error/edge context], when [action], then [graceful handling]
  • Given [error/edge context], when [action], then [user feedback]
Priority: must | Complexity: S/M/L Edge case type: error state | empty state | boundary | permission
As a [persona], I want [behavior when X goes wrong], so that [I can recover / understand what happened].
Acceptance Criteria:
  • Given [error/edge context], when [action], then [graceful handling]
  • Given [error/edge context], when [action], then [user feedback]

Activity 2: <Activity Name>

Activity 2: <Activity Name>

...
undefined
...
undefined

Writing Stories

撰写故事

The Story Statement

故事陈述

Each story has three parts that must all be present:
  • As a [persona]: Use a specific persona from the product profile, not "a user." If no personas exist, define them inline (e.g., "As a first-time customer who has never used the product").
  • I want [action]: Describe the action from the user's perspective. "I want to filter search results" not "I want the system to implement filtering."
  • So that [outcome]: State the user value, not the system behavior. "So that I can find the right item without scrolling through hundreds of results" not "so that the filter query runs on the backend."
每个故事必须包含三个部分：
  • As a [persona]: 使用产品档案中的特定用户角色，而不是“用户”。如果没有用户角色，则在文中定义（例如：“As a first-time customer who has never used the product”）。
  • I want [action]: 从用户的角度描述操作。比如“I want to filter search results”而不是“I want the system to implement filtering”。
  • So that [outcome]: 说明用户价值，而非系统行为。比如“So that I can find the right item without scrolling through hundreds of results”而不是“so that the filter query runs on the backend”。

Acceptance Criteria

验收标准

Every criterion follows Given/When/Then strictly:
  • Given [a specific, reproducible starting state]
  • When [a single user action]
  • Then [an observable, verifiable outcome]
Good: "Given a user with 50+ saved items, when they type 3 characters in the search field, then matching items appear within 500ms and non-matching items are hidden."
Bad: "Given the user is on the page, when they search, then it works correctly."
每条标准严格遵循Given/When/Then格式：
  • Given [特定的、可复现的起始状态]
  • When [单个用户操作]
  • Then [可观察、可验证的结果]
示例（好）：“Given a user with 50+ saved items, when they type 3 characters in the search field, then matching items appear within 500ms and non-matching items are hidden.”
示例（差）：“Given the user is on the page, when they search, then it works correctly.”

Priority Tags

优先级标签

TagMeaningGuidance
mustMVP — feature does not ship without thisCore happy path, critical error handling
shouldImportant but not launch-blockingSecondary workflows, polish, non-critical edge cases
couldNice-to-have, do if time permitsConvenience features, optimizations, advanced scenarios
标签含义指导
mustMVP — 没有此项则功能无法发布核心正常流程、关键错误处理
should重要但不阻碍发布次要工作流、优化、非关键边缘场景
could锦上添花，时间允许时再做便捷功能、优化、高级场景

Complexity Tags

复杂度标签

TagMeaningGuidance
SLess than 1 day of engineering workSingle component, no new APIs, no data model changes
M1-3 days of engineering workMultiple components, may need a new API endpoint or schema change
L3-5 days of engineering workCross-cutting, new infrastructure, significant data model changes
If a story is larger than L, it should be split into smaller stories.
标签含义指导
S少于1天的工程工作量单个组件、无需新API、无数据模型变更
M1-3天的工程工作量多个组件、可能需要新API端点或架构变更
L3-5天的工程工作量跨领域、新基础设施、重大数据模型变更
如果故事复杂度超过L，应拆分为更小的故事。

Output

输出

  • File: 
    .chalk/docs/product/<n>_user_stories_<feature_slug>.md
  • Format: Plain markdown, no YAML frontmatter
  • First line: 
    # User Stories: <Feature Name>
  • Second line: 
    Last updated: <YYYY-MM-DD> (Initial draft)
  • 文件: 
    .chalk/docs/product/<n>_user_stories_<feature_slug>.md
  • 格式: 纯Markdown，无YAML前置元数据
  • 第一行: 
    # User Stories: <Feature Name>
  • 第二行: 
    Last updated: <YYYY-MM-DD> (Initial draft)

Anti-patterns

反模式

  • Stories without acceptance criteria — A story with no Given/When/Then is just a sentence. It cannot be estimated, tested, or verified. Every story gets 2-4 criteria, no exceptions.
  • Missing edge-case stories — Happy-path-only story maps lead to brittle products. Every activity must have at least one edge-case story covering error states, empty states, boundaries, or permissions.
  • Acceptance criteria that are not testable — "The experience should be smooth" cannot be verified. Every criterion must be specific enough that a QA engineer can write a test case from it without asking questions.
  • Stories that are really tasks — "As a developer, I want to set up the database schema" is a task, not a user story. Stories describe user-visible value. Implementation tasks belong in engineering plans, not story maps.
  • "As a user" without specificity — Always use a named persona or a descriptive phrase. "As a user" tells the engineer nothing about who they are building for. "As a warehouse manager checking inventory at end-of-shift" tells them everything.
  • Skipping the story map overview — The summary table is the first thing a PM or stakeholder reads. It shows scope at a glance: how many stories, how they break down by priority. Never omit it.
  • One giant activity — If an activity has more than 8 stories, it is too broad. Split it into two activities. Story maps should be scannable.
  • Duplicating the PRD — Stories operationalize the PRD, they do not restate it. Do not copy-paste problem statements or metrics into the stories doc. Reference the PRD by filename instead.
  • 无验收标准的故事 — 没有Given/When/Then的故事只是一句话。无法进行估算、测试或验证。每个故事都必须有2-4条标准，无例外。
  • 缺少边缘场景故事 — 仅包含正常流程的故事地图会导致产品脆弱。每个活动必须至少有一个涵盖错误状态、空状态、边界或权限的边缘场景故事。
  • 不可测试的验收标准 — “体验应流畅”无法验证。每条标准必须足够具体，让QA工程师无需询问即可编写测试用例。
  • 实为任务的故事 — “As a developer, I want to set up the database schema”是任务，不是用户故事。故事描述的是用户可见的价值。实现任务属于工程计划，而非故事地图。
  • 无具体指向的“作为用户” — 始终使用命名的用户角色或描述性短语。“作为用户”无法让工程师了解他们为谁构建。“作为轮班结束时盘点库存的仓库经理”则能提供全部信息。
  • 跳过故事地图概述 — 汇总表是产品经理或利益相关者首先阅读的内容。它能一目了然地展示范围：有多少故事，按优先级如何划分。绝不能省略。
  • 单一巨型活动 — 如果一个活动包含超过8个故事，则范围过宽。应拆分为两个活动。故事地图应便于快速浏览。
  • 复制PRD内容 — 故事是PRD的落地实现，而非重述。不要将问题陈述或指标复制粘贴到故事文档中。而是通过文件名引用PRD。