Menu
Use when you have an approved PRD and need to break it into actionable user stories for development.
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.
Based on SOC occupation classification
Use when analyzing competitors, understanding competitive landscape, conducting SWOT analysis, or positioning your product against alternatives.
Use when setting up or improving a continuous product discovery practice with weekly customer interviews.
Use when preparing design specifications for engineering handoff and quality assurance.
Use when planning a product or feature launch and preparing go-to-market execution.
Use when you have raw user feedback from multiple sources (interviews, surveys, tickets, reviews) and need to extract themes, patterns, and actionable insights
Use when defining product metrics, designing experiments, analyzing feature adoption, or setting up measurement frameworks.
| name | user-story-writing |
| description | Use when you have an approved PRD and need to break it into actionable user stories for development. |
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."
Do NOT invoke this skill unless the PRD is approved. If the PRD hasn't been written, invoke writing-prd after product-discovery.Save stories to: docs/product-superpowers/stories/YYYY-MM-DD-<feature-name>-stories.md
You MUST create a task for each of these items and complete them in order:
Re-read the approved PRD. Note:
Group related user stories into epics. An epic represents a large body of work that delivers a coherent user outcome.
Epic guidelines:
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
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:
Goal-focused, not feature-focused:
Benefits that connect to outcomes:
Verify every story meets all INVEST criteria:
| Criterion | Check | Red Flag |
|---|---|---|
| Independent | Can this story be developed independently? | "Depends on [other story] being complete" |
| Negotiable | Can details be adjusted during development? | Over-prescribed implementation details |
| Valuable | Does this deliver value to users or the business? | Pure technical stories with no user benefit |
| Estimable | Can the team roughly estimate the effort? | "We don't know enough to estimate" (needs spike) |
| Small | Can it be completed in one sprint? | "This will take the whole team the entire sprint" (too large, split it) |
| Testable | Is there a clear pass/fail condition? | "The user should have a good experience" (vague) |
Stories that fail INVEST must be rewritten, split, or marked as spikes.
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:
For every user-facing story, document:
Before a story enters a sprint, it must be:
Order stories considering:
Draw a slicing line for the Minimum Viable Product (MVP):
[Must have for launch]
───────────────────── Slicing Line
[Nice to have, can ship later]
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]
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."