¶
Quick facts
Phase: Deliver | Version: 2.0.0 | Category: specification | License: Apache-2.0
User Stories¶
User stories are concise descriptions of functionality from the user's perspective. They capture who needs something, what they need, and why — without prescribing how to build it. Good user stories enable teams to break large features into estimable, deliverable increments while maintaining focus on user value.
When to Use¶
- After PRD approval, when breaking down features for implementation
- During sprint planning to create actionable work items
- When writing tickets for engineering teams
- When communicating requirements to stakeholders in accessible terms
- When prioritizing a backlog based on user value
How to Use¶
Use the /user-stories slash command:
Or reference the skill file directly: skills/deliver-user-stories/SKILL.md
Instructions¶
When asked to create user stories, follow these steps:
-
Understand the Feature Context Review the PRD or feature description. Understand the overall goal, target users, and scope boundaries. User stories should trace back to documented requirements.
-
Identify User Personas Determine which users interact with this feature. Each story should be written for a specific persona, not generic "users." Different personas may need different stories for the same feature.
-
Break Down by User Goal Decompose the feature into distinct user goals. Each story should deliver a complete, valuable capability — something the user can actually do when the story is done.
-
Write Story Statements Use the format: "As a [persona], I want [action] so that [benefit]." The benefit clause is critical — it explains why this matters and helps prioritize.
-
Define Acceptance Criteria Write specific, testable criteria using Given/When/Then format. Acceptance criteria define "done" — if all criteria pass, the story is complete.
-
Apply INVEST Criteria Validate each story against INVEST: Independent, Negotiable, Valuable, Estimable, Small, Testable. Revise stories that don't meet these criteria.
-
Add Context and Notes Include relevant design references, technical considerations, and dependencies. These help implementers understand the full picture.
Output Template¶
User Story: [Story Title]¶
Story Header¶
| Field | Value |
|---|---|
| ID | [US-XXX] |
| Title | [Brief descriptive title] |
| Persona | [User persona] |
| Priority | [P0/P1/P2] |
| Epic/Feature | [Parent feature or epic] |
| Estimate | [Story points or T-shirt size] |
User Story Statement¶
As a [specific user persona],
I want [action or capability],
so that [benefit or value I receive].
Context & Background¶
[Context explaining the user need and how this story fits into the larger feature]
Acceptance Criteria¶
AC-1: [Criterion Title]¶
Given [initial context or precondition]
When [action taken by user]
Then [expected outcome]
AC-2: [Criterion Title]¶
Given [initial context or precondition]
When [action taken by user]
Then [expected outcome]
AC-3: [Criterion Title]¶
Given [initial context or precondition]
When [action taken by user]
Then [expected outcome]
Design Notes¶
- [Design note or link to Figma]
- [UX consideration]
Technical Notes¶
- [Technical note]
- [Constraint or consideration]
Dependencies¶
| Dependency | Type | Status |
|---|---|---|
| [Dependency 1] | [Story/API/Team] | [Blocked/Ready] |
| [Dependency 2] | [Story/API/Team] | [Blocked/Ready] |
Out of Scope¶
- [Excluded item]
- [Excluded item]
Open Questions¶
- [Question 1]
- [Question 2]
Example Output¶
User Stories: Recurring Tasks Feature
User Stories: Recurring Tasks Feature¶
This document contains the user stories for the Recurring Tasks feature. See the Recurring Tasks PRD for full context.
Story 1: Create Recurring Task¶
Story Header¶
| Field | Value |
|---|---|
| ID | US-101 |
| Title | Create Recurring Task |
| Persona | Team Lead |
| Priority | P0 |
| Epic/Feature | Recurring Tasks |
| Estimate | 5 points |
User Story Statement¶
As a team lead,
I want to create a task that repeats on a schedule,
so that I don't have to manually recreate recurring work items each week.
Context & Background¶
Team leads manage ongoing operational tasks like weekly status reports, monthly reviews, and recurring team meetings. Currently, they manually duplicate these tasks, which is time-consuming and error-prone. This story enables basic recurring task creation with standard patterns.
Acceptance Criteria¶
AC-1: Recurrence Toggle Available¶
Given I am creating a new task
When I view the task creation form
Then I see a "Make Recurring" toggle option
AC-2: Pattern Selection¶
Given I have enabled the "Make Recurring" toggle
When I view the recurrence options
Then I can select from Daily, Weekly, or Monthly patterns
AC-3: Weekly Day Selection¶
Given I have selected "Weekly" recurrence
When I configure the pattern
Then I can select which days of the week the task should recur (multi-select)
AC-4: Monthly Date Selection¶
Given I have selected "Monthly" recurrence
When I configure the pattern
Then I can choose either a specific date (1-31) or a relative day (e.g., "First Monday")
AC-5: First Instance Created¶
Given I have configured a recurrence pattern and saved the task
When the task is created
Then the first instance appears in my task list with a recurring indicator icon
Design Notes¶
- Recurrence panel expands below task details when toggle is enabled
- Use calendar-style day picker for weekly selection
- Show preview text: "Repeats every Monday and Wednesday"
- See Figma: Recurring Task Creation for mockups
Technical Notes¶
- Store pattern as RRULE format for future calendar sync compatibility
- Generate instances on-demand, not all at once
- First instance due date = task due date; subsequent follow pattern
Dependencies¶
| Dependency | Type | Status |
|---|---|---|
| None | — | Ready |
Out of Scope¶
- Custom patterns (e.g., "every 2 weeks")
- End date configuration (covered in US-105)
Story 2: Edit Single Instance¶
Story Header¶
| Field | Value |
|---|---|
| ID | US-102 |
| Title | Edit Single Instance |
| Persona | Individual Contributor |
| Priority | P0 |
| Epic/Feature | Recurring Tasks |
| Estimate | 3 points |
User Story Statement¶
As an individual contributor,
I want to edit a single occurrence of a recurring task without changing the entire series,
so that I can handle exceptions like rescheduling one meeting without affecting future occurrences.
Context & Background¶
Recurring tasks often need instance-level modifications — a weekly report might have a different deadline one week due to a holiday, or a recurring meeting might have different agenda items. Users need flexibility to modify individual instances without disrupting the overall pattern.
Acceptance Criteria¶
AC-1: Edit Scope Prompt¶
Given I am editing a task that is part of a recurring series
When I modify any field and attempt to save
Then I am prompted to choose "Edit this instance only" or "Edit all future instances"
AC-2: Instance-Only Edit¶
Given I have selected "Edit this instance only"
When I save my changes
Then only the current instance is updated, and future instances retain original values
AC-3: Instance Visual Indicator¶
Given I have edited a single instance
When I view that instance in my task list
Then it displays an indicator showing it differs from the series pattern
AC-4: Series Unaffected¶
Given I have edited a single instance
When I view other instances of the same series
Then they retain the original values from the series template
Design Notes¶
- Modal dialog for edit scope selection
- Modified instances show "edited" badge
- See Figma: Instance Edit Flow for interaction details
Technical Notes¶
- Instance modifications stored as overrides, not new records
- Preserve link to parent series for reporting purposes
Dependencies¶
| Dependency | Type | Status |
|---|---|---|
| US-101 | Story | Ready |
Out of Scope¶
- Editing the recurrence pattern itself (covered in US-103)
- Bulk editing multiple instances
Story 3: View Upcoming Instances¶
Story Header¶
| Field | Value |
|---|---|
| ID | US-103 |
| Title | View Upcoming Instances |
| Persona | Team Lead |
| Priority | P0 |
| Epic/Feature | Recurring Tasks |
| Estimate | 3 points |
User Story Statement¶
As a team lead,
I want to see upcoming instances of my recurring tasks,
so that I can plan my workload and anticipate upcoming deadlines.
Context & Background¶
Visibility into future recurring instances helps users plan their time effectively. Without this, users would only see the current instance and might be surprised by upcoming work. This story ensures recurring tasks are visible in planning views.
Acceptance Criteria¶
AC-1: Future Instances in Task List¶
Given I have a recurring task with future instances
When I view my task list with "Show upcoming" enabled
Then I see the next 4 weeks of instances for that recurring task
AC-2: Instances in Calendar View¶
Given I have a recurring task with future instances
When I view the calendar
Then I see recurring task instances on their scheduled dates
AC-3: Instance Count Display¶
Given I am viewing an instance of a recurring task
When I look at the task details
Then I see which instance this is (e.g., "#3 of series")
AC-4: Series Overview¶
Given I am viewing any instance of a recurring series
When I click "View Series"
Then I see a list of all past and upcoming instances with their status (completed, pending, overdue)
Design Notes¶
- Upcoming instances shown with lighter styling than current tasks
- "View Series" link in task detail panel
- Calendar shows recurring icon on recurring task dates
Technical Notes¶
- Instances generated lazily (on view, not on creation)
- Maximum 4 weeks forward generation to limit database growth
- Consider pagination for series overview if >20 instances
Dependencies¶
| Dependency | Type | Status |
|---|---|---|
| US-101 | Story | Ready |
| Calendar View Refactor | Team | In Progress |
Out of Scope¶
- Filtering task list by recurring vs. one-time
- Exporting series to external calendars
Story 4: Pause Recurring Series¶
Story Header¶
| Field | Value |
|---|---|
| ID | US-104 |
| Title | Pause Recurring Series |
| Persona | Team Lead |
| Priority | P1 |
| Epic/Feature | Recurring Tasks |
| Estimate | 2 points |
User Story Statement¶
As a team lead,
I want to pause a recurring task series temporarily,
so that I can stop generating new instances during holidays or project pauses without deleting the series.
Context & Background¶
Teams often need to temporarily halt recurring tasks — during holiday periods, team transitions, or project pauses. Deleting and recreating the series is cumbersome. A pause mechanism preserves the configuration while stopping new instance generation.
Acceptance Criteria¶
AC-1: Pause Action Available¶
Given I am viewing a recurring task instance
When I open the task actions menu
Then I see a "Pause Series" option
AC-2: Pause Confirmation¶
Given I click "Pause Series"
When the confirmation dialog appears
Then I see a message explaining that no new instances will be generated until resumed
AC-3: Paused Visual State¶
Given I have paused a recurring series
When I view any instance of that series
Then it displays a "Paused" indicator with muted styling
AC-4: Resume Functionality¶
Given I have a paused recurring series
When I click "Resume Series"
Then the series resumes generating instances from the next scheduled date
Design Notes¶
- Pause/Resume toggle in task action menu
- Paused tasks show pause icon and grayed styling
- Resume calculates next instance from today, not from pause date
Technical Notes¶
- Add
paused_attimestamp to series record - Paused series excluded from instance generation job
- Existing instances remain visible but no new ones created
Dependencies¶
| Dependency | Type | Status |
|---|---|---|
| US-101 | Story | Ready |
Out of Scope¶
- Scheduled pause (pause until specific date)
- Auto-resume after X days
INVEST Checklist Summary¶
| Story | Independent | Negotiable | Valuable | Estimable | Small | Testable |
|---|---|---|---|---|---|---|
| US-101 | Yes | Yes | Yes | Yes | Yes | Yes |
| US-102 | Yes (depends on 101) | Yes | Yes | Yes | Yes | Yes |
| US-103 | Yes (depends on 101) | Yes | Yes | Yes | Yes | Yes |
| US-104 | Yes (depends on 101) | Yes | Yes | Yes | Yes | Yes |
Real-World Examples¶
See this skill applied to three different product contexts:
Storevine (B2B): Storevine B2B ecommerce platform — Campaigns guided first-campaign flow user story
Prompt:
/user-stories
Project: Campaigns — native email marketing for Storevine merchants
Sprint: Q2 2026 Campaigns build (kickoff Mar 3, GA Apr 28)
Story I need:
Guided first-campaign flow for non-adopter merchants
Who: Merchant with no active external email tool and no prior Storevine
email sends (non-adopter segment, ~38% of active base [fictional])
What: Send their first email campaign using a pre-populated template seeded
with their own products and a default audience
Why: Start driving repeat purchases without needing to figure out email
marketing from scratch
Prior work to reference:
- Hypothesis: first-send rate target 12% → 30% [fictional] in 60 days
- Spike summary: SendGrid attribution via unique_args confirmed feasible
- Design rationale: pre-built named segments as default audience selection
- PRD: Campaigns v1 scope locked
Need: full user story with acceptance criteria (Given/When/Then),
design notes, technical notes, and dependencies. P0 priority.
Output:
User Story: Guided First-Campaign Flow for Non-Adopter Merchants¶
Brainshelf (Consumer): Brainshelf consumer PKM app — Resurface user stories for Sprint 8
Prompt:
/user-stories
resurface stories for sprint 8. need the full set with acceptance
criteria.
stories:
1. receive daily digest (P0) — the core email delivery
2. opt in to digest (P0) — home screen card + settings toggle
3. click item to read (P0) — one-click from email to article
4. change cadence (P1) — daily vs 3x/week
5. unsubscribe from digest (P0) — one-click from email footer
keep them tight. alex and jess need to estimate on monday.
Output:
User Story: Receive Daily Resurface Digest¶
Workbench (Enterprise): Workbench enterprise collaboration platform - Blueprints v1 sprint stories for required sections and approval gates
Prompt:
/user-stories
I need two user stories for the Blueprints v1 sprint backlog. These are the two highest-priority stories for the first sprint.
**Story 1 -- Required-section enforcement (author perspective):**
- Persona: Ops manager creating a Blueprint from a template with required sections
- Core need: Cannot submit an incomplete document for approval
- Key behaviors: Required sections show a visual indicator; submit button disabled until all required sections have content; if content is deleted, submit re-disables
- Context: Part of the hybrid wizard/canvas flow; applies to both wizard and canvas modes
- Relates to: A/B test hypothesis (required vs. optional sections, Mar 9 -- Apr 5)
**Story 2 -- Approval gate (approver perspective):**
- Persona: Department head reviewing a submitted Blueprint
- Core need: Review complete documents efficiently with clear approve/reject actions
- Key behaviors: Notification on submission; inline section review; approve, reject with required comment, or request changes; Blueprint marked approved when all required approvers complete
- Context: Sequential and parallel approval chains configured per template by admin
For each story, include full acceptance criteria, design notes, technical notes, dependencies, out of scope, and open questions.
Output:
User Story: Required-Section Enforcement for Blueprint Authors¶
Quality Checklist¶
Before finalizing, verify:
- Each story follows "As a... I want... so that..." format
- Stories are independent (can be built in any order)
- Acceptance criteria use Given/When/Then format
- Each criterion is testable (someone can verify pass/fail)
- Stories are small enough to complete in one sprint
- No implementation details in the story statement
- Benefit clause explains why this matters to the user
Output Format¶
Use the template in references/TEMPLATE.md to structure the output.