user-story-fundamentals skill

---
name: user-story-fundamentals
description:
  Capture requirements from user perspective with structured user stories. Use
  when writing backlog items, defining acceptance criteria, prioritizing
  features, or communicating requirements between product and development.
---

# User Story Fundamentals - Capturing User-Centered Requirements

A structured framework for capturing product requirements from the user's
perspective. User stories help teams understand who needs a feature, what they
want to accomplish, and why it matters.

## When to Use This Skill

- Writing backlog items
- Defining feature requirements
- Prioritizing development work
- Communicating with development teams
- Breaking down epics into actionable work
- Ensuring user focus in product decisions

## User Story Format

```
THE STANDARD TEMPLATE

"As a [type of user],
 I want [some goal],
 so that [some reason/benefit]."

Components:
┌─────────────────────────────────────────────────────┐
│  WHO: The user persona or role                      │
│  WHAT: The desired functionality or goal            │
│  WHY: The business value or user benefit            │
└─────────────────────────────────────────────────────┘

This format shifts focus from WRITING about requirements
to TALKING about them, with users at the center.
```

## Core Components

### WHO - User Persona

```
Specificity Spectrum:

Generic (avoid):
├── "As a user..."
└── "As a customer..."

Better:
├── "As a first-time visitor..."
├── "As a returning customer..."
├── "As an admin user..."
└── "As a mobile user..."

Best (with job context):
├── "As a marketing manager who needs weekly reports..."
├── "As a parent shopping for school supplies..."
├── "As a developer debugging production issues..."
└── "As a sales rep preparing for a client meeting..."
```

### WHAT - Desired Functionality

```
Focus on GOALS, not IMPLEMENTATION:

❌ "I want a blue button in the header"
   (prescriptive, limits solutions)

✓ "I want to quickly access my saved items"
   (goal-focused, enables creativity)

❌ "I want a REST API endpoint"
   (technical implementation)

✓ "I want to integrate my data with external tools"
   (user goal, flexible implementation)
```

### WHY - Business Value

```
The "So That" Connection:

This part explains:
├── What pain it solves
├── What value it creates
├── Why this matters to the user
└── How it connects to business goals

Without "so that":
"As a user, I want to filter search results"
→ Why? What's the actual need?

With "so that":
"As a user, I want to filter search results
 so that I can find relevant items faster
 when browsing large catalogs"
→ Clear value, enables better solutions
```

## INVEST Criteria

```
QUALITY CHECKLIST FOR USER STORIES

I - Independent
│   Can be developed and delivered separately
│   No tight coupling to other stories
│
N - Negotiable
│   Details open to discussion
│   Not a rigid contract
│
V - Valuable
│   Delivers real value to user or business
│   Not just technical tasks
│
E - Estimable
│   Team can estimate effort
│   Clear enough to size
│
S - Small
│   Fits within single sprint
│   If too big, split it
│
T - Testable
│   Has clear acceptance criteria
│   Can verify when complete
```

## Acceptance Criteria

### Definition

```
ACCEPTANCE CRITERIA (AC)

Purpose: Define what makes the story "done"
Format: Specific, testable conditions

Example Story:
"As a user, I want to reset my password via email
 so that I can regain access if I forget it"

Acceptance Criteria:
□ User can request reset from login page
□ Email sent within 60 seconds of request
□ Reset link expires after 24 hours
□ Link works only once
□ Password must meet security requirements
□ User receives confirmation after successful reset
```

### Writing Good AC

| Characteristic  | Example                                      |
| --------------- | -------------------------------------------- |
| Specific        | "Within 60 seconds" not "quickly"            |
| Testable        | "Email contains reset link" - can verify     |
| Outcome-focused | "User can access account" not "system sends" |
| Complete        | Covers happy path AND edge cases             |

## Prioritization Framework

### RICE Scoring

```
RICE = (Reach × Impact × Confidence) / Effort

Reach: How many users affected per time period?
       (100 users/month, 1000 users/quarter)

Impact: How much will it move the needle?
        3 = Massive, 2 = High, 1 = Medium, 0.5 = Low, 0.25 = Minimal

Confidence: How sure are we about estimates?
            100% = High, 80% = Medium, 50% = Low

Effort: Person-months of work
        (0.5, 1, 2, 3...)

Higher RICE score = Higher priority
```

### MoSCoW Method

```
CATEGORIZATION FOR RELEASE PLANNING

MUST Have (Non-negotiable)
├── Critical for release
├── Legal/compliance requirements
└── Core value proposition

SHOULD Have (Important)
├── High value but not critical
├── Workarounds exist
└── Strong user demand

COULD Have (Nice to have)
├── Desired but not necessary
├── Easy wins if time permits
└── Lower user impact

WON'T Have (Not this time)
├── Explicitly out of scope
├── Future consideration
└── Documented for later
```

## Story Splitting Techniques

### When to Split

```
SPLIT IF:
├── Can't complete in one sprint
├── Story points > 13 (or team max)
├── Multiple distinct user values
├── Contains "and" connecting features
└── Too many acceptance criteria
```

### Splitting Methods

```
1. BY WORKFLOW STEPS
   Original: "User can complete purchase"
   Split:
   ├── User can add items to cart
   ├── User can enter shipping info
   ├── User can enter payment info
   └── User can confirm and place order

2. BY USER TYPE
   Original: "User can view dashboard"
   Split:
   ├── Admin can view full dashboard
   ├── Manager can view team metrics
   └── User can view personal stats

3. BY OPERATIONS (CRUD)
   Original: "User can manage contacts"
   Split:
   ├── User can create contact
   ├── User can view contact details
   ├── User can edit contact
   └── User can delete contact

4. BY DATA VARIATIONS
   Original: "User can import data"
   Split:
   ├── User can import CSV files
   ├── User can import Excel files
   └── User can import from API

5. BY ACCEPTANCE CRITERIA
   Original: "User can search products"
   Split:
   ├── User can basic keyword search
   ├── User can filter by category
   ├── User can sort results
   └── User can save search
```

## Definition of Done vs. Acceptance Criteria

```
DEFINITION OF DONE (DoD)        ACCEPTANCE CRITERIA (AC)
────────────────────────        ────────────────────────
Universal checklist             Story-specific conditions
Same for all stories            Unique per story
Quality standard                Functional requirements

DoD Examples:                   AC Examples:
□ Code reviewed                 □ User can X
□ Tests written                 □ System does Y
□ Documentation updated         □ Data validates as Z
□ No critical bugs              □ Performance meets N
```

## Story Template

```markdown
## User Story

**ID:** [PROJ-123] **Title:** [Brief descriptive title]

### Story

As a [specific user type], I want [goal/desire], so that [benefit/value].

### Acceptance Criteria

- [ ] [Specific, testable condition 1]
- [ ] [Specific, testable condition 2]
- [ ] [Specific, testable condition 3]

### Notes

- [Additional context]
- [Technical considerations]
- [Dependencies]

### Attachments

- [Link to designs]
- [Link to research]

### Estimation

- **Story Points:** [X]
- **Priority:** [High/Medium/Low]
- **Sprint:** [Sprint N]
```

## Real-World Examples

### E-commerce

```
Story: Password-less Login

As a returning customer,
I want to login using a magic link sent to my email,
so that I can access my account without remembering passwords.

Acceptance Criteria:
□ User enters email on login page
□ "Send magic link" option available
□ Email received within 30 seconds
□ Link valid for 15 minutes
□ One-click login from email
□ User lands on their dashboard after login
□ Link cannot be reused after login
```

### SaaS Product

```
Story: Team Invitation

As an account admin,
I want to invite team members via email,
so that I can onboard my team without manual account creation.

Acceptance Criteria:
□ Admin can enter multiple email addresses
□ Invitation email clearly explains next steps
□ Invited user can set their own password
□ Admin can see pending invitations
□ Admin can revoke pending invitations
□ Duplicate email addresses are prevented
□ Admin can set role during invitation
```

## Common Mistakes

```
ANTI-PATTERNS TO AVOID

❌ Implementation as story
   "Create database table for users"
   → Not user value, technical task

❌ Missing "so that"
   "As a user, I want to search"
   → Why? What problem does this solve?

❌ Too vague
   "As a user, I want a better experience"
   → What specifically? Not actionable

❌ Too large
   "As a user, I want full account management"
   → Multiple features, needs splitting

❌ Solution prescribed
   "As a user, I want a dropdown menu"
   → Describes UI, not user goal
```

## Integration with Other Methods

| Method               | Combined Use                      |
| -------------------- | --------------------------------- |
| **Theme-Epic-Story** | Stories fit within epic hierarchy |
| **Jobs to Be Done**  | Stories address user jobs         |
| **Five Whys**        | Find root cause behind story need |
| **Hypothesis Tree**  | Stories as hypotheses to test     |
| **Kanban**           | Stories flow through board stages |

## Quick Reference

```
STORY WRITING CHECKLIST

Format:
□ Follows "As a... I want... so that..." format
□ User type is specific and meaningful
□ Goal is user-focused, not technical
□ Benefit clearly stated

Quality (INVEST):
□ Independent - can be built alone
□ Negotiable - details discussable
□ Valuable - delivers real value
□ Estimable - team can size it
□ Small - fits in single sprint
□ Testable - has clear AC

Acceptance Criteria:
□ Specific and measurable
□ Testable (can verify pass/fail)
□ Covers main scenarios
□ Includes edge cases
□ Outcome-focused
```

## Resources

- [User Stories Applied - Mike Cohn](https://www.mountaingoatsoftware.com/books/user-stories-applied)
- [User Story Mapping - Jeff Patton](https://www.jpattonassociates.com/user-story-mapping/)
- [Writing Effective User Stories - Scrum Alliance](https://www.scrumalliance.org/)