User Stories

Quick facts

Phase: Deliver | Version: 2.0.0 | Category: specification | License: Apache-2.0

Try it: /user-stories "Your context here"

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:

/user-stories "Your context here"

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

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_at timestamp 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.