user-stories

When this skill is activated, always start your first response with the 🧢 emoji.

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.

1. 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.

1. 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.

1. 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.

1. 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

| Letter | Criterion | What it means | |---|---|---| | I | Independent | Can be developed and delivered without depending on another story | | N | Negotiable | Scope and details can be adjusted before the sprint | | V | Valuable | Delivers perceivable value to a user or the business | | E | Estimable | The team can size it; if not, it needs splitting or a spike | | S | Small | Fits in one sprint; ideally completable in 2-3 days | | T | Testable | Acceptance criteria exist and can be verified |

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.

1. 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.

1. Break activities into tasks - Under each activity, list the user tasks

(specific actions). These become the backbone of your stories.

1. Write stories under tasks - Under each task, write the stories needed to

support it. Stack them vertically with highest priority on top.

1. Draw release slices - Draw horizontal lines through the map. Everything

above the first line = MVP. Everything above the second line = v1.1. Etc.

1. 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 crit