User Story Writing
Turn requirements, feature ideas, and epics into stories a team can estimate and deliver. The product is the story set, not prose about the feature.
Story Format
### [ID] [Title — verb phrase, outcome-oriented]
**As a** [specific user role — not "user"], **I want to** [action], **so that** [value the role actually cares about].
#### Acceptance Criteria
- Given [precondition], when [action], then [observable outcome]
- ...
For system-level or compliance-driven requirements where the persona format gets artificial, use EARS instead:
| EARS pattern |
Template |
Use for |
| Ubiquitous |
The [system] shall [behavior] |
Invariants |
| Event-driven |
When [trigger], the [system] shall [behavior] |
Responses to events |
| State-driven |
While [state], the [system] shall [behavior] |
Mode-dependent behavior |
| Unwanted behavior |
If [undesired condition], then the [system] shall [behavior] |
Error and abuse handling |
| Optional |
Where [feature is included], the [system] shall [behavior] |
Configurable capabilities |
INVEST Check
Run every story against INVEST before delivering; fix violations rather than annotating them:
- Independent — schedulable without forcing another story into the same sprint
- Negotiable — captures intent, not implementation; the "how" stays open
- Valuable — the "so that" names value for the role; "so that the database is updated" fails
- Estimable — a developer could size it; unknowns extracted into spike stories
- Small — fits comfortably in a sprint; otherwise split (see below)
- Testable — every criterion observable; "works correctly" fails
Epic Splitting Patterns
Apply the first pattern that yields shippable slices:
- By workflow step — each step of the user journey is a story (browse → select → pay → confirm).
- Happy path first — story 1 is the simplest successful flow; error handling, edge cases, and limits follow as separate stories.
- By business rule — base behavior first, each rule variation (discounts, regions, roles) its own story.
- By data variation — support one input type first (e.g. domestic transfers), add types incrementally.
- CRUD split — create first, then read/update/delete if each carries real value.
Never split by architectural layer — a "backend story" with nothing demonstrable is not a story.
Definition of Ready
A story is ready for sprint planning when:
Guidelines
- Write criteria the QA engineer can execute verbatim. Vague criteria are deferred arguments.
- Keep the user role honest: if every story says "as a user", the personas were never real. Use the actual role names from the product.
- When given a batch of raw requirements, first group them into epics, present the grouping for confirmation, then split — don't generate 40 stories in one shot.
- Resist gold-plating: if a criterion doesn't trace back to the "so that", cut it.
1---2name: user-story-writing3description: Writes and refines user stories for product backlogs: splits epics into INVEST-compliant stories, drafts Given/When/Then and EARS-format acceptance criteria, and runs definition-of-ready checks. Triggers on: "write user stories", "split this epic", "acceptance criteria for", "refine this story", "is this story ready", "turn these requirements into stories".4license: MIT5---67# User Story Writing89Turn requirements, feature ideas, and epics into stories a team can estimate and deliver. The product is the story set, not prose about the feature.1011## Story Format1213```markdown14### [ID] [Title — verb phrase, outcome-oriented]15**As a** [specific user role — not "user"], **I want to** [action], **so that** [value the role actually cares about].1617#### Acceptance Criteria18- Given [precondition], when [action], then [observable outcome]19- ...20```2122For system-level or compliance-driven requirements where the persona format gets artificial, use EARS instead:2324| EARS pattern | Template | Use for |25|--------------|----------|---------|26| Ubiquitous | The [system] shall [behavior] | Invariants |27| Event-driven | When [trigger], the [system] shall [behavior] | Responses to events |28| State-driven | While [state], the [system] shall [behavior] | Mode-dependent behavior |29| Unwanted behavior | If [undesired condition], then the [system] shall [behavior] | Error and abuse handling |30| Optional | Where [feature is included], the [system] shall [behavior] | Configurable capabilities |3132## INVEST Check3334Run every story against INVEST before delivering; fix violations rather than annotating them:3536- **I**ndependent — schedulable without forcing another story into the same sprint37- **N**egotiable — captures intent, not implementation; the "how" stays open38- **V**aluable — the "so that" names value for the role; "so that the database is updated" fails39- **E**stimable — a developer could size it; unknowns extracted into spike stories40- **S**mall — fits comfortably in a sprint; otherwise split (see below)41- **T**estable — every criterion observable; "works correctly" fails4243## Epic Splitting Patterns4445Apply the first pattern that yields shippable slices:46471. **By workflow step** — each step of the user journey is a story (browse → select → pay → confirm).482. **Happy path first** — story 1 is the simplest successful flow; error handling, edge cases, and limits follow as separate stories.493. **By business rule** — base behavior first, each rule variation (discounts, regions, roles) its own story.504. **By data variation** — support one input type first (e.g. domestic transfers), add types incrementally.515. **CRUD split** — create first, then read/update/delete if each carries real value.5253Never split by architectural layer — a "backend story" with nothing demonstrable is not a story.5455## Definition of Ready5657A story is ready for sprint planning when:5859- [ ] Acceptance criteria cover the happy path AND at least one failure/edge path60- [ ] Dependencies identified (other stories, external teams, data)61- [ ] Security consideration noted where the story touches auth, money, or personal data (one line; use the security-story-writing skill for dedicated security stories)62- [ ] UX reference attached where there's a user interface63- [ ] Team can estimate it without a meeting-length discussion6465## Guidelines6667- Write criteria the QA engineer can execute verbatim. Vague criteria are deferred arguments.68- Keep the user role honest: if every story says "as a user", the personas were never real. Use the actual role names from the product.69- When given a batch of raw requirements, first group them into epics, present the grouping for confirmation, then split — don't generate 40 stories in one shot.70- Resist gold-plating: if a criterion doesn't trace back to the "so that", cut it.
timwukp