User Stories

User stories are short, plain-language descriptions of a feature from the perspective of the person who wants it. They are the primary unit of work in agile teams - a shared, human-readable contract between product, design, and engineering that keeps teams focused on user value rather than technical implementation details.

When to use this skill

Trigger this skill when the user:

• Wants to write or improve a user story
• Needs to define acceptance criteria for a feature
• Is creating or facilitating a story mapping session
• Wants to groom or refine a product backlog
• Needs to estimate stories with story points or t-shirt sizes
• Asks about INVEST criteria or whether a story is well-formed
• Needs to split a large story or epic into smaller deliverable stories
• Wants to write technical stories, spikes, or enabler stories

Do NOT trigger this skill for:

• Sprint planning ceremonies (scheduling and capacity work, not story writing)
• Project roadmaps and OKRs (strategy-level, above story granularity)

Key principles

1. INVEST criteria - Every story should be Independent, Negotiable, Valuable, Estimable, Small, and Testable. A story that fails any criterion needs rework before it enters a sprint. See the Core Concepts section for the full breakdown.

2. Acceptance criteria are testable - Acceptance criteria must be written so that a tester (human or automated) can unambiguously determine pass or fail. Vague criteria like "the UI should look good" are not acceptance criteria - they are opinions. Rewrite them as concrete, observable outcomes.

3. Vertical slices, not horizontal - A story must deliver end-to-end value: a real user doing a real thing and getting a real result. A story that covers only the database layer, only the API, or only the UI is a task, not a story. Horizontal slicing creates work that sits unfinished for sprints; vertical slicing enables continuous delivery.

4. Conversation over documentation - The written story is a placeholder for a conversation, not a complete specification. The three C's (Card, Conversation, Confirmation) mean the card captures the intent, the team talks through details during grooming and planning, and acceptance criteria confirm shared understanding. Resist writing exhaustive specifications - keep the card short and talk.

5. Stories are negotiable - The "N" in INVEST. A story is not a contract. The team and product owner negotiate scope, approach, and details right up until the sprint begins. If a story cannot be adjusted, it is a requirement document masquerading as a story.

Core concepts

Story anatomy

The standard template - "As a [persona], I want [action], so that [outcome]" - has three parts, each carrying weight:

• Persona (As a...) - Who benefits? Use a real persona or role, not "user" or "system." The persona grounds every decision in a real person's need.
• Action (I want...) - What do they want to do? This is the feature, stated as a user action, not a system capability.
• Outcome (So that...) - Why do they want it? The business or user value. This is the most important part - it prevents teams from building the wrong thing correctly.

INVEST criteria

Acceptance criteria formats

Given/When/Then (Gherkin) is the most structured format and maps directly to automated tests:

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

Checklist format works for stories with multiple independent outcomes:

- [ ] User can sort the table by any column
- [ ] Sort order persists across page refreshes
- [ ] Default sort is by date descending

Use Gherkin for behavior-critical paths (auth, payments, core flows). Use checklists for UI stories with many small, independent criteria.

Story mapping

Story mapping organizes stories into a two-dimensional grid:

• Horizontal axis (Backbone) - User activities in the order a user experiences them (left to right). These are big-bucket steps like "Browse catalog," "Add to cart," "Checkout," "Receive order."
• Vertical axis (Depth) - Stories under each activity, ordered by priority (top = must-have, bottom = nice-to-have).
• Horizontal slices - Drawing a line across all activities at the same depth creates a release slice that delivers a complete, thin version of the product.

Common tasks

Write effective user stories

Template:

As a [specific persona],
I want [specific action],
So that [measurable outcome].

Weak story (before):

As a user, I want to search, so that I can find things.

Strong story (after):

As a returning customer,
I want to search my order history by product name or order date,
So that I can quickly find and re-order items I've bought before.

The strong version names the persona, specifies the exact action, and ties the outcome to a real business motivation (re-orders).

Checklist before writing:

1. Is the persona specific enough to guide design decisions?
2. Is the action a user action, not a system behavior?
3. Does the "so that" capture user or business value - not technical rationale?
4. Can this be delivered in a single sprint?

Write acceptance criteria - GWT format

Write one scenario per distinct behavior. Cover the happy path first, then edge cases and error states.

Story: As a shopper, I want to apply a discount code at checkout, so that I receive the discount on my order total.

Scenario: Valid discount code applied
Given the shopper has items in their cart totaling $80
When they enter a valid 20%-off code "SAVE20" at checkout
Then the order total shows $64.00
And the applied discount is itemized on the order summary

Scenario: Expired discount code
Given a discount code "SUMMER22" that expired on 2022-09-01
When the shopper enters "SUMMER22" at checkout
Then an error message reads "This code has expired"
And the order total is unchanged

Scenario: Code already used (single-use code)
Given the shopper has already used single-use code "WELCOME10"
When they enter "WELCOME10" again at checkout
Then an error message reads "This code has already been used"

Create a story map - step by step

1. Define the user - Agree on which user (persona) the map is for. One map per primary user type.
2. List user activities - Brainstorm the big steps the user takes (post-its, one per card). Arrange left to right in user journey order. Aim for 5-10 activities.
3. Break activities into tasks - Under each activity, list the user tasks (specific actions). These become the backbone of your stories.
4. Write stories under tasks - Under each task, write the stories needed to support it. Stack them vertically with highest priority on top.
5. Draw release slices - Draw horizontal lines through the map. Everything above the first line = MVP. Everything above the second line = v1.1. Etc.
6. Validate the slices - Each slice should be a coherent, releasable product. Ask: "Could a user get value from only what's above this line?"

Groom and refine backlog

Run a grooming session against each story using this checklist:

• Clear? Can the team explain it back in their own words?
• INVEST? Does it pass all six criteria?
• Acceptance criteria complete? At least one happy-path scenario, one error case.
• Dependencies identified? Are blockers noted and tracked?
• Ready to estimate? If the team cannot size it, create a spike story.
• Definition of Done applicable? Does standard DoD cover this, or are there story-specific done criteria?

If a story fails more than two items, send it back to the product owner for rework rather than attempting to fix it in the grooming meeting.

Estimate with story points - relative sizing

Story points measure complexity + uncertainty + effort relative to a reference story, not time.

Step-by-step with planning poker:

1. Select a reference story the whole team agrees is "a 3." Post it visibly.
2. Read the new story aloud. Give everyone a moment to think silently.
3. All team members reveal their estimate simultaneously (cards or app).
4. If estimates converge (within one Fibonacci step): accept the majority or average.
5. If estimates diverge: the highest and lowest estimators explain their reasoning. Discuss until convergence, then re-estimate once.

Fibonacci scale: 1, 2, 3, 5, 8, 13, 21, ? (unknown), infinity (too large)

Sizing heuristics:

Split large stories - patterns

See references/story-splitting.md for the full 10-pattern reference.

Quick reference - top 3 patterns:

1. By workflow step - Break the story at each step in the user's process. "As a user, I want to complete checkout" splits into: enter shipping address / enter payment / review and confirm / receive confirmation email.

2. By data variation - If a story handles many types of input, start with the simplest type and add variations in follow-on stories. "Search by name" / "search by date" / "search by category."

3. Happy path first - Implement the success case, defer error handling and edge cases to a follow-on story. Always ship the happy path first.

Write technical stories and spikes

Technical story template:

In order to [technical goal / business benefit],
As [team or role],
We need to [technical action].

Example:

In order to meet the 200ms API response SLA,
As the platform team,
We need to add a Redis cache layer in front of the product catalog endpoint.

Spike template (time-boxed research):

Spike: [question to answer]
Timebox: [hours]
Output: [what the team will have at the end - a decision, a prototype, an ADR]

Example:

Spike: Evaluate Stripe vs. Braintree for payment processing
Timebox: 8 hours
Output: Decision doc with recommendation, covering integration complexity,
        fee structure, and PCI compliance implications

Spikes produce knowledge, not shippable software. Always define what "done" looks like before starting.

Anti-patterns

Gotchas

1. "So that" written as a technical rationale defeats the purpose - "So that the database is updated" or "so that the API returns 200" describes implementation, not user value. If the "so that" clause could be written by an engineer rather than a user, rewrite it from the user's perspective - what can they now do or feel that they couldn't before?

2. Stories estimated without the team who will build them are not estimates - Point estimates assigned by product managers or scrum masters without engineer input are not commitments the engineering team made. Only the team doing the work should size the stories.

3. INVEST "Independent" is aspirational, not absolute - Some dependencies are unavoidable (auth before user profiles). The rule is to minimize hidden dependencies, not eliminate all sequencing. Expose dependencies explicitly in the story as a "Depends on:" note rather than pretending they don't exist.

4. Acceptance criteria written as UI wireframes lock in a solution prematurely - "The button is blue and in the top-right corner" as an acceptance criterion prevents design iteration. Write behavior ("user can dismiss the notification at any time") and let design solve the visual implementation.

5. Spikes without a defined output become open-ended research sinkholes - A spike with no output criteria runs until time is up and delivers a dump of information rather than a decision. Always define: what specific question will be answered, and what artifact (decision doc, ADR, prototype) will exist when the spike is done.

References

• references/story-splitting.md - 10 patterns for splitting large stories with worked examples for each. Load when a story is too large or an epic needs breaking down.