# User Stories

> When to activate: user stories, as a user I want, acceptance criteria, story splitting, story mapping, epic, backlog, agile

- Skill: `mattakushi432/user-stories` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mattakushi432/user-stories`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mattakushi432/user-stories/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: Mattakushi432 (https://skillmd.com/u/mattakushi432)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mattakushi432/user-stories

---


# User Stories

## Core Format

```
As a [persona],
I want to [action/capability],
So that [benefit/outcome].
```

### Good vs Bad Examples
```
BAD: As a user, I want a dashboard so that I can see things.
GOOD: As a marketing manager, I want to see campaign ROI by channel,
      so that I can reallocate budget to the highest-performing channels.

BAD: As an admin, I want to manage users.
GOOD: As an account admin, I want to invite team members by email with role assignment,
      so that I can control who has access to which features without IT involvement.
```

## Persona Types
- Use specific personas, not "user" (admin, developer, end-user, free user, enterprise customer)
- Personas should reflect real segments in your user research
- Different personas can have conflicting stories — make them explicit

## Acceptance Criteria

### INVEST Criteria (good story checklist)
- **I**ndependent: Can be built without other stories (mostly)
- **N**egotiable: Implementation details are open
- **V**aluable: Delivers value to user or business
- **E**stimable: Team can size it
- **S**mall: Completable in one sprint
- **T**estable: Acceptance criteria are verifiable

### Writing Acceptance Criteria

**Format 1: Given/When/Then**
```
Story: As a buyer, I want to filter products by price range
       so that I can find items within my budget.

AC-1:
  GIVEN I am on the product listing page
  WHEN I set a price range of $10–$50
  THEN only products priced between $10 and $50 are displayed
  AND the count shows the number of filtered results

AC-2:
  GIVEN I set min price > max price
  WHEN I try to apply the filter
  THEN I see an inline error "Min price must be less than max price"
  AND the filter is not applied

AC-3:
  GIVEN no products match the price range
  WHEN filter is applied
  THEN empty state is shown with "No products found. Try a wider range."
```

**Format 2: Checklist**
```
Story: As a user, I want to export my data as CSV

Acceptance Criteria:
  - [ ] Export button visible to all users with data
  - [ ] Clicking export triggers download within 3 seconds for < 10k rows
  - [ ] File is named: [feature]-export-YYYY-MM-DD.csv
  - [ ] Headers match column labels in the UI
  - [ ] Unicode characters are encoded correctly (UTF-8 BOM)
  - [ ] For > 10k rows, email download link within 5 minutes
  - [ ] Email includes expiry note: link valid 24 hours
  - [ ] Export is logged in audit trail
```

## Story Splitting Techniques (SPIDR)

### S — Spikes
Split research/technical uncertainty from implementation:
```
Spike: Investigate OAuth2 providers for social login (2 days → recommendation)
Story: Implement Google OAuth2 sign-in (after spike)
Story: Implement GitHub OAuth2 sign-in (after spike)
```

### P — Paths (Workflow Variations)
Split by user path:
```
Original: As a user, I want to sign in
Split:
  Story 1: Sign in with email/password
  Story 2: Sign in with Google SSO
  Story 3: Sign in with magic link
  Story 4: Sign in on mobile (biometric)
```

### I — Interfaces
Split by platform/channel:
```
Original: Users can receive notifications
Split:
  Story 1: In-app notifications (bell icon)
  Story 2: Email notifications
  Story 3: Slack notifications
  Story 4: Mobile push notifications
```

### D — Data
Split by data complexity:
```
Original: Support all payment methods
Split:
  Story 1: Credit card (Stripe)
  Story 2: PayPal
  Story 3: ACH / bank transfer
  Story 4: International wire transfer
```

### R — Rules (Business Logic)
Split by business rule:
```
Original: Calculate pricing
Split:
  Story 1: Standard pricing (no discounts)
  Story 2: Volume discounts
  Story 3: Coupon/promo code application
  Story 4: Enterprise contract pricing
```

## Story Mapping

### Layout
```
User Activities (top row — goals)
│
├── Discover product
│   ├── See homepage         (step)
│   ├── Read blog post       (step)
│   └── Watch demo video     (step)
│
├── Sign up
│   ├── Fill signup form     (step)
│   ├── Verify email         (step)
│   └── Complete profile     (step)
│
└── First success
    ├── Create first item    (step)
    ├── Invite teammate      (step)
    └── See first insight    (step)

Release 1 (MVP — must have)
═══════════════════════════════
[Card] [Card]        [Card]

Release 2 (better UX)
═══════════════════════════════
        [Card] [Card]

Release 3 (polish)
═══════════════════════════════
                     [Card]
```

## Epic Decomposition

### Epic Template
```
Epic: [Outcome-oriented title]
Goal: [Metric we're moving and by how much]
Why Now: [Strategic reason for prioritization]

Stories:
1. [Story 1] — [Size] — [Sprint target]
2. [Story 2] — [Size] — [Sprint target]
3. [Story 3] — [Size] — [Sprint target]

Definition of Done (Epic):
- [ ] All stories shipped to 100% of users
- [ ] Target metric achieved
- [ ] Docs updated
- [ ] Support trained
```

### Epic Size Guidelines
| T-Shirt | Story Points | Sprint Duration |
|---------|-------------|-----------------|
| XS | 1-3 | < 1 sprint |
| S | 3-8 | 1 sprint |
| M | 8-20 | 1-2 sprints |
| L | 20-40 | 2-3 sprints |
| XL | 40+ | Split into sub-epics |

## Story Point Estimation (Planning Poker)

### Fibonacci Scale Reference
```
1: Trivial — copy change, tooltip update
2: Very small — simple UI element, config change
3: Small — single form field with validation
5: Medium — new page with standard CRUD
8: Complex — integration with external API
13: Large — multi-step flow with state management
21: Very large — split this story
```

### Relative Estimation Rules
- Estimate complexity, not time
- Compare to a known reference story
- Account for testing and code review
- When estimates diverge by >2x, discuss before revoting

## Story Definition of Done
- [ ] Code reviewed and merged
- [ ] Unit tests written (coverage maintained)
- [ ] Acceptance criteria verified in staging
- [ ] No regressions in related areas
- [ ] Feature flag configured (if applicable)
- [ ] Analytics events firing correctly
- [ ] Copy reviewed (no placeholder text)
- [ ] Accessibility checked (keyboard nav, screen reader)
- [ ] Performance: no LCP/CLS regressions
- [ ] Product owner signed off in staging