User Stories
Write high-quality, INVEST-compliant user stories with testable acceptance criteria.
User Story Template
As a [persona],
I want to [action/capability],
So that [benefit/value].
Example:
As a marketing manager,
I want to export campaign reports to PDF,
So that I can share results with stakeholders who don't have system access.
Story Types
| Type |
Template |
Example |
| Feature |
As a [persona], I want to [action] so that [benefit] |
As a user, I want to filter search results so that I find items faster |
| Improvement |
As a [persona], I need [capability] to [goal] |
As a user, I need faster page loads to complete tasks without frustration |
| Bug Fix |
As a [persona], I expect [behavior] when [condition] |
As a user, I expect my cart to persist when I refresh the page |
| Enabler |
As a developer, I need to [technical task] to enable [capability] |
As a developer, I need to implement caching to enable instant search |
Persona Reference
| Persona |
Typical Needs |
Context |
| End User |
Efficiency, simplicity, reliability |
Daily feature usage |
| Administrator |
Control, visibility, security |
System management |
| Power User |
Automation, customization, shortcuts |
Expert workflows |
| New User |
Guidance, learning, safety |
Onboarding |
Adapt personas to your project. Use specific names when possible (e.g., "store owner" instead of "end user").
INVEST Criteria
Validate every story before adding it to the backlog:
| Criterion |
Question |
Pass If... |
| Independent |
Can this be developed without other uncommitted stories? |
No blocking dependencies |
| Negotiable |
Is the implementation flexible? |
Multiple approaches possible |
| Valuable |
Does this deliver user or business value? |
Clear benefit in "so that" |
| Estimable |
Can the team estimate this? |
Understood well enough to size |
| Small |
Can this complete in one iteration? |
Reasonably scoped |
| Testable |
Can we verify this is done? |
Clear acceptance criteria |
Acceptance Criteria
Given-When-Then Template
Given [precondition/context],
When [action/trigger],
Then [expected outcome].
Examples:
Given the user is logged in with valid credentials,
When they click the "Export" button,
Then a PDF download starts within 2 seconds.
Given the user has entered an invalid email format,
When they submit the registration form,
Then an inline error message displays "Please enter a valid email address."
Given the shopping cart contains items,
When the user refreshes the browser,
Then the cart contents remain unchanged.
AC Checklist
Each story should include criteria for applicable categories:
| Category |
Example |
| Happy Path |
Given valid input, When submitted, Then success message displayed |
| Validation |
Should reject input when required field is empty |
| Error Handling |
Must show user-friendly message when API fails |
| Performance |
Should complete operation within 2 seconds |
| Accessibility |
Must be navigable via keyboard only |
Not every category applies to every story. Use judgment.
Minimum Criteria by Story Size
| Size |
Minimum AC Count |
| Small (trivial) |
2-3 criteria |
| Medium |
4-6 criteria |
| Large |
5-8 criteria |
| Too large |
Split the story |
INVEST Failure Patterns
| Criterion |
Red Flag |
Fix |
| Independent |
"After story X is done..." |
Combine stories or resequence |
| Negotiable |
Specific implementation in story |
Focus on outcome, not solution |
| Valuable |
No "so that" clause |
Add benefit statement |
| Estimable |
Team says "no idea" |
Spike first, then story |
| Small |
Too large to finish in one iteration |
Split into smaller stories |
| Testable |
"System should be better" |
Add measurable criteria |
Story Splitting
When a story is too large, split using one of these techniques:
| Technique |
Example |
| By workflow step |
"Create order" -> "Add items" + "Apply discount" + "Submit order" |
| By persona |
"User dashboard" -> "Admin dashboard" + "Member dashboard" |
| By data type |
"Import data" -> "Import CSV" + "Import Excel" |
| By operation |
"Manage users" -> "Add user" + "Edit user" + "Delete user" |
| Happy path first |
"Full feature" -> "Basic flow" + "Error handling" + "Edge cases" |
Common Antipatterns
Story Antipatterns
| Antipattern |
Example |
Fix |
| Solution story |
"Implement React component" |
"Display user profile information" |
| Compound story |
"Create, edit, and delete users" |
Split into three stories |
| Missing persona |
"The system will..." |
"As an admin, I want to..." |
| No benefit |
"I want to see a button" |
Add "so that [benefit]" |
| Too vague |
"Improve performance" |
"Reduce page load to <2 seconds" |
| Technical jargon |
"Implement Redis caching" |
"Enable instant search results" |
Acceptance Criteria Antipatterns
| Antipattern |
Example |
Fix |
| Too vague |
"Works correctly" |
Specific Given-When-Then |
| Implementation details |
"Use PostgreSQL query" |
Focus on outcome |
| Missing unhappy path |
Only success scenario |
Add error cases |
| Untestable |
"User is happy" |
Measurable behavior |
| Too many |
15+ criteria |
Split the story |
References
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: user-stories3description: Write INVEST-compliant user stories with Given-When-Then acceptance criteria. Use when writing user stories, creating acceptance criteria, or during /design Step 4. Use when this capability is needed.4---56# User Stories78Write high-quality, INVEST-compliant user stories with testable acceptance criteria.910---1112## User Story Template1314```15As a [persona],16I want to [action/capability],17So that [benefit/value].18```1920**Example:**21```22As a marketing manager,23I want to export campaign reports to PDF,24So that I can share results with stakeholders who don't have system access.25```2627---2829## Story Types3031| Type | Template | Example |32|------|----------|---------|33| Feature | As a [persona], I want to [action] so that [benefit] | As a user, I want to filter search results so that I find items faster |34| Improvement | As a [persona], I need [capability] to [goal] | As a user, I need faster page loads to complete tasks without frustration |35| Bug Fix | As a [persona], I expect [behavior] when [condition] | As a user, I expect my cart to persist when I refresh the page |36| Enabler | As a developer, I need to [technical task] to enable [capability] | As a developer, I need to implement caching to enable instant search |3738---3940## Persona Reference4142| Persona | Typical Needs | Context |43|---------|--------------|---------|44| End User | Efficiency, simplicity, reliability | Daily feature usage |45| Administrator | Control, visibility, security | System management |46| Power User | Automation, customization, shortcuts | Expert workflows |47| New User | Guidance, learning, safety | Onboarding |4849Adapt personas to your project. Use specific names when possible (e.g., "store owner" instead of "end user").5051---5253## INVEST Criteria5455Validate every story before adding it to the backlog:5657| Criterion | Question | Pass If... |58|-----------|----------|------------|59| **I**ndependent | Can this be developed without other uncommitted stories? | No blocking dependencies |60| **N**egotiable | Is the implementation flexible? | Multiple approaches possible |61| **V**aluable | Does this deliver user or business value? | Clear benefit in "so that" |62| **E**stimable | Can the team estimate this? | Understood well enough to size |63| **S**mall | Can this complete in one iteration? | Reasonably scoped |64| **T**estable | Can we verify this is done? | Clear acceptance criteria |6566---6768## Acceptance Criteria6970### Given-When-Then Template7172```73Given [precondition/context],74When [action/trigger],75Then [expected outcome].76```7778**Examples:**79```80Given the user is logged in with valid credentials,81When they click the "Export" button,82Then a PDF download starts within 2 seconds.8384Given the user has entered an invalid email format,85When they submit the registration form,86Then an inline error message displays "Please enter a valid email address."8788Given the shopping cart contains items,89When the user refreshes the browser,90Then the cart contents remain unchanged.91```9293### AC Checklist9495Each story should include criteria for applicable categories:9697| Category | Example |98|----------|---------|99| Happy Path | Given valid input, When submitted, Then success message displayed |100| Validation | Should reject input when required field is empty |101| Error Handling | Must show user-friendly message when API fails |102| Performance | Should complete operation within 2 seconds |103| Accessibility | Must be navigable via keyboard only |104105Not every category applies to every story. Use judgment.106107### Minimum Criteria by Story Size108109| Size | Minimum AC Count |110|------|------------------|111| Small (trivial) | 2-3 criteria |112| Medium | 4-6 criteria |113| Large | 5-8 criteria |114| Too large | Split the story |115116---117118## INVEST Failure Patterns119120| Criterion | Red Flag | Fix |121|-----------|----------|-----|122| Independent | "After story X is done..." | Combine stories or resequence |123| Negotiable | Specific implementation in story | Focus on outcome, not solution |124| Valuable | No "so that" clause | Add benefit statement |125| Estimable | Team says "no idea" | Spike first, then story |126| Small | Too large to finish in one iteration | Split into smaller stories |127| Testable | "System should be better" | Add measurable criteria |128129---130131## Story Splitting132133When a story is too large, split using one of these techniques:134135| Technique | Example |136|-----------|---------|137| By workflow step | "Create order" -> "Add items" + "Apply discount" + "Submit order" |138| By persona | "User dashboard" -> "Admin dashboard" + "Member dashboard" |139| By data type | "Import data" -> "Import CSV" + "Import Excel" |140| By operation | "Manage users" -> "Add user" + "Edit user" + "Delete user" |141| Happy path first | "Full feature" -> "Basic flow" + "Error handling" + "Edge cases" |142143---144145## Common Antipatterns146147### Story Antipatterns148149| Antipattern | Example | Fix |150|-------------|---------|-----|151| Solution story | "Implement React component" | "Display user profile information" |152| Compound story | "Create, edit, and delete users" | Split into three stories |153| Missing persona | "The system will..." | "As an admin, I want to..." |154| No benefit | "I want to see a button" | Add "so that [benefit]" |155| Too vague | "Improve performance" | "Reduce page load to <2 seconds" |156| Technical jargon | "Implement Redis caching" | "Enable instant search results" |157158### Acceptance Criteria Antipatterns159160| Antipattern | Example | Fix |161|-------------|---------|-----|162| Too vague | "Works correctly" | Specific Given-When-Then |163| Implementation details | "Use PostgreSQL query" | Focus on outcome |164| Missing unhappy path | Only success scenario | Add error cases |165| Untestable | "User is happy" | Measurable behavior |166| Too many | 15+ criteria | Split the story |167168---169170## References171172- Based on [agile-product-owner](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner) by [alirezarezvani](https://github.com/alirezarezvani) (MIT License)173- Adapted and reduced to user story focus only (no sprint planning, velocity tracking, or epic breakdown)174175---176> Converted and distributed by [TomeVault](https://tomevault.io/claim/b33eep) — claim your Tome and manage your conversions.177<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io