---
title: "User Stories"
description: "Generates user stories with clear acceptance criteria from product requirements or feature descriptions. Use when breaking down features for sprint planning, writing tickets, or communicating requirements to engineering."
generated: true
source: scripts/generate-skill-pages.py
tags:
  - Deliver
  - specification
---

:::note[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:

1. **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.

2. **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.

3. **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.

4. **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.

5. **Define Acceptance Criteria**
   Write specific, testable criteria using Given/When/Then format. Acceptance criteria define "done" . if all criteria pass, the story is complete.

6. **Apply INVEST Criteria**
   Validate each story against INVEST: Independent, Negotiable, Valuable, Estimable, Small, Testable. Revise stories that don't meet these criteria.

7. **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

<!-- Why does this story exist? What problem does it solve? Link to PRD if available. -->

[Context explaining the user need and how this story fits into the larger feature]

## Acceptance Criteria

<!-- Use Given/When/Then format. Each criterion should be independently testable. -->

### 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

<!-- Link to mockups, UX considerations, or design decisions -->

- [Design note or link to Figma]
- [UX consideration]

## Technical Notes

<!-- Implementation hints, technical constraints, or architectural considerations -->

- [Technical note]
- [Constraint or consideration]

## Dependencies

<!-- Other stories, external systems, or teams this story depends on -->

| Dependency | Type | Status |
|------------|------|--------|
| [Dependency 1] | [Story/API/Team] | [Blocked/Ready] |
| [Dependency 2] | [Story/API/Team] | [Blocked/Ready] |

## Out of Scope

<!-- Explicitly note what this story does NOT cover -->

- [Excluded item]
- [Excluded item]

## Open Questions

<!-- Unresolved questions that may affect implementation -->

- [ ] [Question 1]
- [ ] [Question 2]

## Example Output

<details>
<summary>User Stories: Recurring Tasks Feature</summary>

# 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 |

</details>

## Real-World Examples

See this skill applied to three different product contexts:

<details>
<summary>Storevine (B2B): Storevine B2B ecommerce platform . Campaigns guided first-campaign flow user story</summary>

**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

</details>

<details>
<summary>Brainshelf (Consumer): Brainshelf consumer PKM app . Resurface user stories for Sprint 8</summary>

**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

</details>

<details>
<summary>Workbench (Enterprise): Workbench enterprise collaboration platform - Blueprints v1 sprint stories for required sections and approval gates</summary>

**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

</details>

## 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.
