Create user stories with Mike Cohn format and Gherkin acceptance criteria. Use when turning user needs into development-ready work with clear outcomes and testable conditions.

Purpose Create clear, concise user stories that combine Mike Cohn's user story format with Gherkin style acceptance criteria. Use this to translate user needs into actionable development work that focuses on outcomes, ensures shared understanding between product and engineering, and provides testable success criteria. This is not a feature spec—it's a conversation starter that captures who benefits, what they're trying to do, why it matters, and how you'll know it works. Input Works best with: The feature or user need the story captures. Also useful: The user role, the outcome they want, and edge cases the acceptance criteria must cover. Anything supplied with the invocation itself — text after the skill name, a pasted context dump, or an appended ARGUMENTS: line — counts as answers already given. Use it and skip whatever it covers; don't re ask. Arriving empty handed? That works too. The skill asks who the user is and what they're trying to accomplish before drafting story and Gherkin criteria. Example invocation: Write user stories for password reset via SMS for our banking app — include the lockout edge case. Key Concepts The Mike Cohn + Gherkin Format A user story combines: Use Case (Mike Cohn format): As a [user persona/role] I want to [action to achieve outcome] so that [desired outcome] Acceptance Criteria (Gherkin format): Scenario: [Brief description of the scenario] Given: [Initial context or preconditions] and Given: [Additional preconditions] When: [Event that triggers the action] Then: [Expected outcome] Why This Structure Works User centric: Forces focus on who benefits and why Outcome focused: "So that" emphasizes the value delivered, not just the action Testable: Gherkin acceptance criteria are concrete and verifiable Conversational: Story is the opening for discussion, not the final spec Shared language: Product, engineering, and QA all understand the format Anti Patterns (What This Is NOT) Not a task: "As a developer, I want to refactor the database" (this is a tech task, not user value) Not a feature list: "I want dashboards, reports, and analytics" (this is too big—needs splitting) Not vague: "I want a better experience" (unmeasurable, no clear outcome) Not a contract: Stories are placeholders for conversation, not locked in specs When to Use This Translating user needs into development work Backlog grooming and sprint planning Communicating value to engineering and design Ensuring testable acceptance criteria exist before development When NOT to Use This For pure technical debt or refactoring (use engineering tasks instead) When stories are too large (split first—see skills/user story splitting/SKILL.md ) Before understanding the user problem (write a problem statement first) Application Step 1: Gather Context Before writing a story, ensure you have: User persona: Who is this for? (reference skills/proto persona/SKILL.md ) Problem understanding: What need does this address? (reference skills/problem statement/SKILL.md ) Desired outcome: What does success look like? Constraints: Technical, time, or scope limitations If missing context: Run discovery interviews or problem validation work first. Optional Helper Script (Template Generator) If you want a consistent Markdown stub, you can generate one from CLI inputs. This script is deterministic and does not fetch data or write files. Step 2: Write the Use Case Use template.md for the full fill in structure. Fill in the template: Quality checks: "As a" specificity: Is this a specific persona (e.g., "trial user") or generic ("user")? "I want to" clarity: Is this an action the user takes, or a feature you're building? "So that" outcome: Does this explain the user's motivation? Or is it just restating the action? Common mistakes: ❌ "As a user, I want a login button, so that I can log in" (restating the action) ✅ "As a trial user, I want to log in with Google, so that I can access the app without creating a new password" Step 3: Write the Acceptance Criteria Fill in the template: Quality checks: Multiple Givens are okay: Preconditions stack up (e.g., "Given I'm logged in" + "Given I have items in my cart") Only one When: If you need multiple "When" statements, you likely have multiple stories—split them Only one Then: If you need multiple "Then" statements, you likely have multiple stories—split them Alignment: Does "When" match "I want to"? Does "Then" match "so that"? Red flags: Multiple Whens/Thens: Sign of scope creep—split the story (reference skills/user story splitting/SKILL.md ) Vague Thens: "Then I see improved performance" (unmeasurable—make it specific) Step 4: Add a Summary Write a short, memorable summary that captures the story's value: Examples: ✅ "Enable Google login for trial users to reduce signup friction" ✅ "Bulk delete items to save time for power users" ❌ "Add delete button" (feature centric, not value centric) Step 5: Validate and Refine Read aloud to the team: Does everyone understand who, what, why? Test acceptance criteria: Can QA write test cases from this? Check for splitting: If the story feels too big, use skills/user story splitting/SKILL.md Ensure testability: Can you prove "Then" happened? Examples See examples/sample.md for full examples (good, bad, and split needed stories). Mini example excerpt: Common Pitfalls Pitfall 1: Technical Tasks Disguised as User Stories Symptom: "As a developer, I want to refactor the API, so that the code is cleaner" Consequence: This is an engineering task, not a user story. No user value is delivered. Fix: If there's no user outcome, it's not a user story—use an engineering task or tech debt ticket instead. Pitfall 2: "As a User" (Too Generic) Symptom: Every story starts with "As a user" Consequence: No persona clarity. Different users have different needs. Fix: Use specific personas: "As a trial user," "As a paid subscriber," "As an admin," etc. (reference skills/proto persona/SKILL.md ) Pitfall 3: "So That" Restates "I Want To" Symptom: "I want to click the save button, so that I can save my work" Consequence: No insight into why the user cares. Just restating the action. Fix: Dig into the motivation: "so that I don't lose my progress if the page crashes" (real outcome). Pitfall 4: Multiple When/Then Statements Symptom: Acceptance criteria with 5 "When" statements and 5 "Then" statements Consequence: Story is too big. Likely multiple features bundled together. Fix: Split the story using skills/user story splitting/SKILL.md . Each When/Then pair should be its own story (or at least evaluated for splitting). Pitfall 5: Untestable Acceptance Criteria Symptom: "Then the user has a better experience" or "Then it's faster" Consequence: QA can't verify success. Ambiguous definition of "done." Fix: Make it measurable: "Then the page loads in under 2 seconds" or "Then the user sees a success confirmation message." References Related Skills skills/user story splitting/SKILL.md — How to break large stories into smaller ones skills/proto persona/SKILL.md — Defines the "As a [persona]" section skills/problem statement/SKILL.md — Stories should address validated problems skills/epic hypothesis/SKILL.md — Epics decompose into user stories Optional Helpers skills/user story/scripts/user story template.py — Deterministic Markdown stub generator (no network access) External Frameworks Mike Cohn, User Stories Applied (2004) — Origin of the "As a / I want / so that" format Gherkin (Cucumber) — "Given/When/Then" acceptance criteria format INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable) Dean's Work [Link to relevant Dean Peters' Substack articles if applicable] Provenance Adapted from prompts/user story prompt template.md in the https://github.com/deanpeters/product manager prompts repo. Skill type: Component Suggested filename: user story.md Suggested placement: /skills/components/ Dependencies: References skills/proto persona/SKILL.md , skills/problem statement/SKILL.md Used by: skills/user story splitting/SKILL.md , skills/epic hypothesis/SKILL.md

user-story