User Story Writing

Writing User Stories

Break an approved PRD into actionable user stories organized into epics. Each story must satisfy INVEST criteria and include Gherkin-format acceptance criteria with edge cases and error states.

Announce at start: "I'm using the user-story-writing skill to break the PRD into user stories."

Save stories to: docs/product-superpowers/stories/YYYY-MM-DD-<feature-name>-stories.md

Checklist

You MUST create a task for each of these items and complete them in order:

1. Review the PRD — Ensure you understand the full scope, metrics, and constraints
2. Identify epics — Group related functionality into epics organized by user journey or theme
3. Write user stories for each epic — Use the standard format with clear personas
4. Apply INVEST to every story — Verify each story meets all criteria
5. Write acceptance criteria — Gherkin format (Given-When-Then) for each story
6. Cover edge cases and error states — Explicitly document all states
7. Define Definition of Ready — What must be true before a story enters a sprint
8. Prioritize and sequence — Order stories within and across epics
9. Save and present for review — Write to docs, get user approval

The Process

Step 1: Review the PRD

Re-read the approved PRD. Note:

• All features and their descriptions
• Success metrics
• Non-functional requirements
• Constraints and dependencies
• What's explicitly out of scope
• User personas mentioned

Step 2: Identify Epics

Group related user stories into epics. An epic represents a large body of work that delivers a coherent user outcome.

Epic guidelines:

• Named after a user outcome, not a technical component
• Contains 3-10 user stories
• Can span multiple sprints but should have a clear finish line
• Each epic should be independently valuable if possible

Example epic structure:

Epic: New User Onboarding
  └── Story: Sign up with email
  └── Story: Sign up with Google SSO
  └── Story: Complete profile setup
  └── Story: Guided product tour
  └── Story: Skip onboarding entirely

Epic: Core Dashboard
  └── Story: View key metrics at a glance
  └── Story: Filter dashboard by date range
  └── Story: Export dashboard as PDF
  └── Story: Customize dashboard layout

Step 3: Write User Stories

Use the standard format:

As a [specific user persona]
I want to [goal or desire]
So that [reason or benefit]

Persona-driven, not role-driven:

• Good: "As a first-time project manager setting up their team..."
• Bad: "As a user..."

Goal-focused, not feature-focused:

• Good: "I want to invite team members by email so that everyone can access the project"
• Bad: "I want an invite button"

Benefits that connect to outcomes:

• Good: "...so that I don't have to manually track who has access"
• Bad: "...so that the system records their email"

Step 4: Apply INVEST Criteria

Verify every story meets all INVEST criteria:

Stories that fail INVEST must be rewritten, split, or marked as spikes.

Step 5: Write Acceptance Criteria (Gherkin)

For each story, write acceptance criteria in Given-When-Then format:

Given [precondition or context]
When [action or event]
Then [expected outcome]

Examples:

Story: Sign up with email

Given I am on the sign-up page
When I enter a valid email and password and click "Create Account"
Then I am redirected to the dashboard
And I receive a welcome email
And my account is created in the database

Given I am on the sign-up page
When I enter an email that is already registered and click "Create Account"
Then I see the error message "An account with this email already exists"
And I am shown a link to "Sign in instead"

Given I am on the sign-up page
When I enter an invalid email format and click "Create Account"
Then I see the error message "Please enter a valid email address"
And the form is not submitted

Given I am on the sign-up page
When I enter a password shorter than 8 characters and click "Create Account"
Then I see the error message "Password must be at least 8 characters"
And the password field is highlighted

Given I am on the sign-up page
When I click "Create Account" with all fields empty
Then I see validation errors on all required fields
And the form is not submitted

Acceptance criteria best practices:

• Write from the user's perspective (what they see, what happens)
• Be specific enough to test, general enough to allow implementation creativity
• Include both happy path AND error/edge cases
• Each scenario is independently testable
• Don't duplicate the story description — criteria define BOUNDARIES
• Use concrete data in examples (realistic names, emails, values)
• Cover all states: default, loading, empty, error, success, edge cases

Step 6: Cover Edge Cases and Error States

For every user-facing story, document:

• Data limits: What happens when the user enters maximum/minimum values?
• Empty states: What does the user see when there's no data?
• Loading states: What does the user see while data is loading?
• Slow/failed network: What happens when the request times out or fails?
• Concurrent actions: What happens if the user double-clicks?
• Accessibility: What's the keyboard navigation, screen reader experience?
• Internationalization: RTL layouts, long text in German, short text in English
• Permissions: What do different roles see?

Step 7: Define Definition of Ready (DoR)

Before a story enters a sprint, it must be:

• User story is written and follows the format
• INVEST criteria are met
• Acceptance criteria are written in Gherkin format
• Edge cases and error states are documented
• Design assets are available (if visual)
• Dependencies are identified and resolved or accepted
• Team has discussed and understands the story
• Story is small enough to complete in one sprint
• Success metrics are linked (if applicable)

Step 8: Prioritize and Sequence

Order stories considering:

1. Dependencies — What must be built first?
2. User journey — What's the natural user flow?
3. Value — What delivers the most user/business value?
4. Risk — What's the riskiest assumption to test?
5. Learning — What teaches us the most about whether we're on the right track?

Draw a slicing line for the Minimum Viable Product (MVP):

[Must have for launch]
───────────────────── Slicing Line
[Nice to have, can ship later]

Step 9: Save and Present

Document structure:

# [Feature Name] — User Stories

**Date:** YYYY-MM-DD
**Based on PRD:** [link to PRD file]
**Status:** Draft / Approved / In Progress

## Epic 1: [Epic Name]

**Outcome:** [What user outcome does this epic deliver?]

### Story 1.1: [Story Title]

**As a** [persona]
**I want to** [goal]
**So that** [benefit]

**Priority:** Must Have / Should Have / Could Have
**Estimate:** [Story Points / T-shirt size]
**Dependencies:** [List any]

**Acceptance Criteria:**
[Gherkin scenarios]

**Edge Cases:**
[List]

**Definition of Ready:**
[Checklist items specific to this story]

---

### Story 1.2: [Story Title]
...

## Epic 2: [Epic Name]
...

## Story Map (Visual)
[ASCII or describe the story map: user journey horizontal, priority vertical]

## MVP Scope
[What's above the slicing line]

User Review Gate

After completing all stories:

"User stories written and saved to docs/product-superpowers/stories/<filename>.md. The document includes [N] epics with [M] stories, INVEST-validated with Gherkin acceptance criteria. Please review and let me know if you want changes."

Key Principles

• Stories are placeholders for conversations — They capture intent, not every detail. Details emerge during development.
• Acceptance criteria define DONE — If it passes the ACs, it's done. If not, it's not.
• INVEST is a quality gate — Stories that fail INVEST don't enter sprints.
• Small stories > big stories — Split until each fits in a sprint (ideally a few days).
• Stories deliver user value — If a story doesn't deliver value to a user or the business, it's probably a task, not a story.
• Every state must be designed — Default, hover, active, focus, disabled, loading, empty, error, success.

Common Mistakes

• Writing stories that are too large (epic disguised as story)
• Stories without clear acceptance criteria ("I'll know it when I see it")
• Technical stories disguised as user stories ("As a developer, I want to refactor the database")
• Stories that depend on other stories (fails Independent in INVEST)
• Acceptance criteria that dictate implementation ("Use a dropdown component")
• No error states or edge cases documented
• Personas that are too generic ("As a user...")
• Stories without a clear benefit clause ("So that..." is missing or vague)

Key References

• "User Story Mapping" by Jeff Patton
• Atlassian's Agile guides on user stories
• "Essential Scrum" by Kenneth Rubin
• INVEST criteria (originated by Bill Wake)
• Gherkin/Cucumber specification format