Use this skill when writing user stories, defining acceptance criteria, story mapping, grooming backlogs, or estimating work. Triggers on user stories, acceptance criteria, story mapping, backlog grooming, estimation, story points, INVEST criteria, and any task requiring agile requirements documentation.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use this skill when writing user stories, defining acceptance criteria, story mapping, grooming backlogs, or estimating work. Triggers on user stories, acceptance criteria, story mapping, backlog grooming, estimation, story points, INVEST criteria, and any task requiring agile requirements documentation.
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
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.
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.
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.
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.
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:
Is the persona specific enough to guide design decisions?
Is the action a user action, not a system behavior?
Does the "so that" capture user or business value - not technical rationale?
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
Define the user - Agree on which user (persona) the map is for. One map
per primary user type.
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.
Break activities into tasks - Under each activity, list the user tasks
(specific actions). These become the backbone of your stories.
Write stories under tasks - Under each task, write the stories needed to
support it. Stack them vertically with highest priority on top.
Draw release slices - Draw horizontal lines through the map. Everything
above the first line = MVP. Everything above the second line = v1.1. Etc.
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:
Select a reference story the whole team agrees is "a 3." Post it visibly.
Read the new story aloud. Give everyone a moment to think silently.
All team members reveal their estimate simultaneously (cards or app).
If estimates converge (within one Fibonacci step): accept the majority or average.
If estimates diverge: the highest and lowest estimators explain their reasoning.
Discuss until convergence, then re-estimate once.
Too large for one sprint. Must split before committing
?
Team doesn't understand the story - needs a spike
Split large stories - patterns
See references/story-splitting.md for the full 10-pattern reference.
Quick reference - top 3 patterns:
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.
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."
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
Anti-pattern
Why it's wrong
What to do instead
The system story ("The system shall...")
Hides the user; focuses on implementation, not value
Rewrite from the user's perspective. Who benefits? Why?
Horizontal story ("Build the database layer")
Not deliverable as standalone value; creates half-built features
Slice vertically through all layers for a thin, complete feature
Acceptance criteria as UI wireframes
Wireframes constrain solutions prematurely and can't be automated
Write behavior in Given/When/Then; let design solve the UI problem
Gold-plating in acceptance criteria
Defining every micro-interaction as a criterion bloats stories
Cover behavior, not aesthetics. Reserve UI polish for design specs
Mega-stories (epic masquerading as a story)
Too large to estimate reliably or complete in one sprint
Split using the patterns in references/story-splitting.md
Missing "so that"
Team builds the feature without understanding why; leads to wrong solutions
Always complete the outcome clause. If you can't, the story isn't ready
Gotchas
"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?
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.
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.
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.
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.
Companion check
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
