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.
Workflow
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.
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.
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.
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)
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)
Determine the next file number — Read filenames in .chalk/docs/product/ to find the highest numbered file. The next number is highest + 1.
Write the file — Save to .chalk/docs/product/<n>_user_stories_<feature_slug>.md.
Confirm — Tell the user the stories were created, share the file path, total story count, and the must/should/could breakdown.
Story Map Structure
# User Stories: <Feature Name>
Last updated: <YYYY-MM-DD> (Initial draft)
Source PRD: [<PRD title>](./<prd_filename>.md) (or "None — stories written from feature description")
## Story Map Overview
| Activity | Must | Should | Could | Total |
|----------|------|--------|-------|-------|
| <activity 1> | X | Y | Z | N |
| <activity 2> | X | Y | Z | N |
| **Total** | **X** | **Y** | **Z** | **N** |
---
## Activity 1: <Activity Name>
<1-sentence description of what the user is doing and why>
### 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]
### Story 1.2: <Short story 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]
---
## Activity 2: <Activity Name>
...
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."
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."
Priority Tags
| Tag |
Meaning |
Guidance |
| must |
MVP — feature does not ship without this |
Core happy path, critical error handling |
| should |
Important but not launch-blocking |
Secondary workflows, polish, non-critical edge cases |
| could |
Nice-to-have, do if time permits |
Convenience features, optimizations, advanced scenarios |
Complexity Tags
| Tag |
Meaning |
Guidance |
| S |
Less than 1 day of engineering work |
Single component, no new APIs, no data model changes |
| M |
1-3 days of engineering work |
Multiple components, may need a new API endpoint or schema change |
| L |
3-5 days of engineering work |
Cross-cutting, new infrastructure, significant data model changes |
If a story is larger than L, it should be split into smaller stories.
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)
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.
1---2name: create-user-stories-23description: Generate user story map with BDD acceptance criteria when the user asks to create user stories, write stories, or break down a feature into stories4---5
6# Create User Stories
7
8## Overview
9
10Generate 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.
11
12## Workflow
13
141. **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.
15
162. **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.
17
183. **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.
19
204. **Write stories for each activity** — Under each activity, write stories from highest to lowest priority. Each story gets:
21 - The story statement: "As a [persona], I want [action], so that [outcome]"
22 - 2-4 acceptance criteria in Given/When/Then format
23 - A priority tag: must (MVP), should (important but not blocking), could (nice-to-have)
24 - A complexity tag: S (< 1 day), M (1-3 days), L (3-5 days)
25
265. **Generate edge-case stories** — For every activity, add at least one story covering:
27 - Error states (what happens when things go wrong)
28 - Empty states (first-time use, no data available)
29 - Boundary conditions (max limits, large inputs, concurrent access)
30 - Permission boundaries (unauthorized user, expired session, role restrictions)
31
326. **Determine the next file number** — Read filenames in `.chalk/docs/product/` to find the highest numbered file. The next number is `highest + 1`.
33
347. **Write the file** — Save to `.chalk/docs/product/<n>_user_stories_<feature_slug>.md`.
35
368. **Confirm** — Tell the user the stories were created, share the file path, total story count, and the must/should/could breakdown.
37
38## Story Map Structure
39
40```markdown
41# User Stories: <Feature Name>
42
43Last updated: <YYYY-MM-DD> (Initial draft)
44
45Source PRD: [<PRD title>](./<prd_filename>.md) (or "None — stories written from feature description")
46
47## Story Map Overview
48
49| Activity | Must | Should | Could | Total |
50|----------|------|--------|-------|-------|
51| <activity 1> | X | Y | Z | N |
52| <activity 2> | X | Y | Z | N |
53| **Total** | **X** | **Y** | **Z** | **N** |
54
55---
56
57## Activity 1: <Activity Name>
58
59<1-sentence description of what the user is doing and why>
60
61### Story 1.1: <Short story title>
62
63**Priority**: must | **Complexity**: S/M/L
64
65As a [persona], I want [action], so that [outcome].
66
67**Acceptance Criteria**:
68- Given [context], when [action], then [expected result]
69- Given [context], when [action], then [expected result]
70- Given [context], when [action], then [expected result]
71
72### Story 1.2: <Short story title>
73
74...
75
76### Story 1.E1: <Edge case title>
77
78**Priority**: must | **Complexity**: S/M/L
79**Edge case type**: error state | empty state | boundary | permission
80
81As a [persona], I want [behavior when X goes wrong], so that [I can recover / understand what happened].
82
83**Acceptance Criteria**:
84- Given [error/edge context], when [action], then [graceful handling]
85- Given [error/edge context], when [action], then [user feedback]
86
87---
88
89## Activity 2: <Activity Name>
90
91...
92```
93
94## Writing Stories
95
96### The Story Statement
97
98Each story has three parts that must all be present:
99
100- **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").
101- **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."
102- **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."
103
104### Acceptance Criteria
105
106Every criterion follows Given/When/Then strictly:
107
108- **Given** [a specific, reproducible starting state]
109- **When** [a single user action]
110- **Then** [an observable, verifiable outcome]
111
112Good: "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."
113
114Bad: "Given the user is on the page, when they search, then it works correctly."
115
116### Priority Tags
117
118| Tag | Meaning | Guidance |
119|-----|---------|----------|
120| must | MVP — feature does not ship without this | Core happy path, critical error handling |
121| should | Important but not launch-blocking | Secondary workflows, polish, non-critical edge cases |
122| could | Nice-to-have, do if time permits | Convenience features, optimizations, advanced scenarios |
123
124### Complexity Tags
125
126| Tag | Meaning | Guidance |
127|-----|---------|----------|
128| S | Less than 1 day of engineering work | Single component, no new APIs, no data model changes |
129| M | 1-3 days of engineering work | Multiple components, may need a new API endpoint or schema change |
130| L | 3-5 days of engineering work | Cross-cutting, new infrastructure, significant data model changes |
131
132If a story is larger than L, it should be split into smaller stories.
133
134## Output
135
136- **File**: `.chalk/docs/product/<n>_user_stories_<feature_slug>.md`
137- **Format**: Plain markdown, no YAML frontmatter
138- **First line**: `# User Stories: <Feature Name>`
139- **Second line**: `Last updated: <YYYY-MM-DD> (Initial draft)`
140
141## Anti-patterns
142
143- **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.
144- **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.
145- **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.
146- **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.
147- **"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.
148- **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.
149- **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.
150- **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.
majiayu000