product-prd-user-stories-acceptance

Writing effective user stories, epics, acceptance criteria, and story mapping for product requirements

PRD User Stories & Acceptance Criteria

Scope: Techniques for writing epics, user stories, acceptance criteria, story mapping, and edge case coverage Lines: ~300 Last Updated: 2025-10-25 Format Version: 1.0 (Atomic)

When to Use This Skill

Activate this skill when:

Core Concepts

Concept 1: Epic, Story, Task Hierarchy

Epic: Large feature or initiative spanning multiple sprints

User Story: Single piece of functionality from user perspective

Task: Technical implementation step (engineering breaks stories into tasks)

Concept 2: INVEST Criteria for User Stories

Independent: Story can be developed without dependencies on other stories Negotiable: Details can be discussed and refined during development Valuable: Delivers clear value to user or business Estimable: Engineering can estimate effort required Small: Fits within one sprint (typically <5 days) Testable: Has clear pass/fail acceptance criteria

Concept 3: Acceptance Criteria Formats

GIVEN-WHEN-THEN (Behavior-Driven Development):

Checklist Format:

Scenario-Based:

Patterns

Pattern 1: Epic Template

When to use:

# Epic: User Authentication System

## Epic Goal
Enable users to securely create accounts, log in, and manage their credentials.

## User Segments
- New users (signing up for first time)
- Returning users (logging in)
- Users who forgot password

## Success Metrics
- 90% of signups complete within 2 minutes
- <1% failed login rate due to technical issues
- Password reset flow completion rate >80%

## User Stories (7 total)
1. ✅ Sign up with email and password
2. ✅ Verify email address
3. 🔄 Log in with email and password
4. ⏳ Reset forgotten password
5. ⏳ Enable two-factor authentication
6. ⏳ Update password from settings
7. ⏳ Log out and clear session

## Out of Scope
- Social login (Google, GitHub) - defer to Q2
- Biometric authentication - future consideration
- Single Sign-On (SSO) - enterprise feature, separate epic

## Dependencies
- Email service provider integration (SendGrid)
- Security review for password hashing approach

Pattern 2: User Story Template (Standard)

Use case: Writing clear, testable user stories

## User Story: Sign Up with Email

**As a** new user
**I want** to create an account using my email and password
**So that** I can access personalized features and save my data

### Acceptance Criteria

**GIVEN** I am on the signup page
**WHEN** I enter a valid email, password (8+ chars, 1 number, 1 symbol), and confirm password
**THEN** the system creates my account and sends a verification email

**GIVEN** I am on the signup page
**WHEN** I enter an email that's already registered
**THEN** I see an error message "Email already in use. Try logging in."

**GIVEN** I am on the signup page
**WHEN** I enter a password that doesn't meet requirements
**THEN** I see real-time validation feedback (e.g., "Password must include a number")

**GIVEN** I successfully signed up
**WHEN** I check my email inbox
**THEN** I receive a verification email within 1 minute with a working verification link

### Edge Cases
- Email with special characters (e.g., user+tag@example.com) - should work
- Very long email (>100 chars) - should validate and accept up to 254 chars
- Network failure during signup - should show error, allow retry
- Duplicate submission (double-click signup button) - should prevent duplicate accounts

### Out of Scope (This Story)
- Password strength meter (separate story)
- Social login options (deferred)
- CAPTCHA for bot prevention (if spam becomes issue)

### Estimation
- Story Points: 3
- Confidence: High

Pattern 3: Acceptance Criteria - Checklist Format

Use case: Simple features with clear requirements

## User Story: Export Data as CSV

**As a** data analyst
**I want** to export my dashboard data as a CSV file
**So that** I can analyze it in Excel or other tools

### Acceptance Criteria
- [ ] "Export CSV" button is visible on dashboard
- [ ] Clicking button downloads a CSV file with correct filename (e.g., "dashboard-data-2025-10-25.csv")
- [ ] CSV includes all visible data rows (respects current filters)
- [ ] CSV columns match dashboard column headers
- [ ] Date fields are formatted as YYYY-MM-DD
- [ ] Numbers include proper decimal separators (based on user locale)
- [ ] Export completes in <5 seconds for up to 10,000 rows
- [ ] User sees loading indicator during export
- [ ] Error message shown if export fails (e.g., network issue)

### Test Cases
1. Happy path: 100 rows, all filters off → CSV downloads correctly
2. Large dataset: 10,000 rows → completes in <5 seconds
3. Filtered data: Date filter applied → CSV only includes filtered rows
4. Empty data: No rows to export → Show "No data to export" message
5. Network failure: API error → Show error message, allow retry

Pattern 4: Scenario-Based Acceptance Criteria

Use case: Complex workflows with multiple paths

## User Story: Password Reset Flow

**As a** user who forgot my password
**I want** to reset it via email link
**So that** I can regain access to my account

### Acceptance Criteria

**Scenario 1: Successful Password Reset**
- User navigates to "Forgot Password" page
- User enters registered email address
- System sends reset email within 1 minute
- User clicks reset link in email (valid for 24 hours)
- User enters new password (meets requirements)
- System updates password and logs user in
- Old password no longer works

**Scenario 2: Unregistered Email**
- User enters email not in system
- System shows generic message: "If email exists, reset link sent" (security)
- No email is actually sent
- Prevents email enumeration attacks

**Scenario 3: Expired Reset Link**
- User receives reset email
- User clicks link after 24 hours
- System shows "Reset link expired. Request a new one."
- User can request new reset link

**Scenario 4: Reused Reset Link**
- User requests reset link
- User successfully resets password
- User tries to use same link again
- System shows "Reset link already used. Request a new one."

**Scenario 5: Password Requirements Not Met**
- User clicks reset link
- User enters password without number/symbol
- System shows real-time validation errors
- User cannot submit until requirements met

Pattern 5: Story Mapping for User Journeys

Use case: Organizing stories by user workflow to identify gaps

## Story Map: User Onboarding Journey

### Backbone (Major Activities)
1. Discover Product
2. Sign Up
3. Complete Profile
4. First Use
5. Become Active User

### User Stories (organized by activity)

**1. Discover Product**
- View marketing homepage
- Watch product demo video
- Read case studies

**2. Sign Up** ⭐ MVP PRIORITY
- Create account with email
- Verify email address
- Accept terms of service

**3. Complete Profile**
- Add profile photo
- Set display name
- Configure preferences

**4. First Use** ⭐ MVP PRIORITY
- See onboarding tutorial
- Complete first task (e.g., create project)
- Invite team member (optional)

**5. Become Active User**
- Use product 3 days in a row (habit formation)
- Complete 10 tasks (engagement milestone)
- Upgrade to paid plan (conversion)

### MVP Slice (Walking Skeleton)
- Create account with email ✅
- Verify email address ✅
- See onboarding tutorial ✅
- Complete first task ✅

### Post-MVP Additions
- Profile customization
- Team invitations
- Advanced tutorials

Pattern 6: Story Estimation with T-Shirt Sizing

Use case: Quick estimation during backlog grooming

## Story Sizing Reference

**XS (1 point)**: ~1-2 hours
- Add a label to a form field
- Change button color
- Update copy on a page

**S (2 points)**: ~half day
- Add a new form field with validation
- Create a simple filter
- Add sorting to a table

**M (3 points)**: ~1 day
- Build a new form with 5-10 fields
- Implement search with filters
- Add CSV export

**L (5 points)**: ~2-3 days
- Create new dashboard page
- Implement authentication flow
- Build API integration with third-party service

**XL (8 points)**: ~1 week
- Design and implement new database schema
- Build real-time notification system
- Create complex data visualization

**TOO BIG (13+ points)**: Break down into smaller stories
- "Build entire user management system" → Split into epics/stories

Pattern 7: Edge Cases and Error Scenarios Checklist

Use case: Ensuring comprehensive acceptance criteria

## Edge Cases Checklist for User Stories

### Input Validation
- [ ] Empty input (required fields)
- [ ] Extremely long input (>1000 chars)
- [ ] Special characters (unicode, emojis, SQL injection attempts)
- [ ] Input with only whitespace
- [ ] Invalid format (e.g., malformed email)

### State Transitions
- [ ] Action performed twice (idempotency)
- [ ] Action performed by two users simultaneously (concurrency)
- [ ] User navigates away mid-process
- [ ] User hits back button
- [ ] Session expires during action

### Network and Performance
- [ ] Network failure mid-request
- [ ] Slow network (<1 Mbps)
- [ ] Request timeout
- [ ] Large payload (>10 MB)
- [ ] API rate limit hit

### Permissions and Access
- [ ] Unauthenticated user attempts action
- [ ] User without proper permissions
- [ ] User accessing another user's data
- [ ] Expired authentication token

### Browser and Device
- [ ] Mobile vs desktop
- [ ] Different browsers (Chrome, Safari, Firefox)
- [ ] Old browser versions (IE11 if required)
- [ ] Screen readers (accessibility)
- [ ] Slow device (older hardware)

### Data States
- [ ] Empty state (no data to display)
- [ ] Single item
- [ ] Thousands of items (pagination needed?)
- [ ] Deleted or archived items
- [ ] Corrupted data

Pattern 8: User Story with Non-Functional Requirements

Use case: Including performance, security, accessibility requirements in stories

## User Story: Real-Time Dashboard Updates

**As a** operations manager
**I want** dashboard metrics to update in real-time
**So that** I can monitor system health without refreshing

### Functional Acceptance Criteria
- Dashboard connects to WebSocket on page load
- Metrics update within 2 seconds of backend event
- Visual indicator shows connection status (green = connected)
- If connection lost, auto-reconnects within 5 seconds
- User can manually refresh if needed

### Non-Functional Requirements

**Performance (NFR)**:
- [ ] Updates render without blocking UI thread
- [ ] Supports 1,000+ concurrent connections per server
- [ ] Memory usage stays <50MB per client session
- [ ] CPU usage <10% on client during updates

**Security (NFR)**:
- [ ] WebSocket uses WSS (encrypted)
- [ ] Authentication token validated on connection
- [ ] Connection closes after 30 min of inactivity
- [ ] Rate limiting: max 100 messages/sec per client

**Accessibility (NFR)**:
- [ ] Screen reader announces new data updates
- [ ] Updates don't interrupt keyboard navigation
- [ ] Visual updates paired with ARIA live regions
- [ ] Color changes have sufficient contrast (WCAG AA)

**Reliability (NFR)**:
- [ ] Graceful degradation if WebSocket unavailable (poll instead)
- [ ] Exponential backoff for reconnection attempts
- [ ] Circuit breaker after 5 failed reconnections
- [ ] Error tracking/logging for connection failures

Quick Reference

User Story Checklist (INVEST)

Criteria | Question to Ask
---------|----------------
Independent | Can this be developed without waiting for other stories?
Negotiable | Are implementation details flexible?
Valuable | Does this deliver user/business value?
Estimable | Can engineering estimate this?
Small | Can this be completed in 1 sprint?
Testable | Are there clear pass/fail criteria?

Acceptance Criteria Format Guide

Format | Best For | Example
-------|----------|--------
GIVEN-WHEN-THEN | Behavior-driven, multiple scenarios | Login flow, form validation
Checklist | Simple features, clear requirements | Export CSV, UI changes
Scenario-Based | Complex workflows, branching paths | Password reset, multi-step forms

Story Estimation Quick Guide

Size | Effort | Examples
-----|--------|----------
XS (1) | 1-2 hours | Copy changes, style tweaks
S (2) | Half day | New form field, simple filter
M (3) | 1 day | Full form, search feature
L (5) | 2-3 days | Dashboard page, auth flow
XL (8) | 1 week | Complex integration, new schema

Key Guidelines

✅ DO: Write from user perspective (not implementation details)
✅ DO: Include edge cases and error scenarios
✅ DO: Make acceptance criteria testable (clear pass/fail)
✅ DO: Keep stories small (completable in one sprint)
✅ DO: Involve engineering in story refinement

❌ DON'T: Write stories as tasks ("Create API endpoint")
❌ DON'T: Prescribe implementation ("Use React hooks")
❌ DON'T: Make stories too large (break epics into stories)
❌ DON'T: Skip non-functional requirements (performance, security)
❌ DON'T: Write vague acceptance criteria ("should work well")

Anti-Patterns

Critical Violations

❌ Task Disguised as User Story: Writing implementation tasks instead of user value

# ❌ NEVER:
**As a** developer
**I want** to create a REST API endpoint for user data
**So that** the frontend can call it

# ✅ CORRECT:
**As a** dashboard user
**I want** to see my profile information displayed
**So that** I can verify my account details are correct

[Engineering will decide if this needs new API endpoint]

❌ Vague Acceptance Criteria: "Should be fast" instead of measurable requirements

# ❌ Don't:
- Dashboard should load fast
- Form should be easy to use

# ✅ Correct:
- Dashboard loads in <2 seconds on 3G network
- Form has real-time validation with clear error messages
- Form is keyboard-navigable (all fields reachable via Tab)

Common Mistakes

❌ Epic-Sized Story: Story too large to complete in one sprint

# ❌ Don't:
"As a user, I want a complete user management system"

# ✅ Correct: Break into stories
- Story 1: Create user account with email
- Story 2: Edit user profile
- Story 3: Deactivate user account
- Story 4: List all users (admin)

❌ Missing Edge Cases: Only happy path in acceptance criteria

# ❌ Don't:
GIVEN I enter valid credentials
WHEN I click login
THEN I am logged in

# ✅ Correct: Include error scenarios
- Valid credentials → Login succeeds
- Invalid password → Error message shown
- Account locked (3 failed attempts) → Locked message shown
- Network failure → Error message, retry button

❌ Technical Implementation in User Story: Dictating how to build it

# ❌ Don't:
"As a user, I want the app to use Redis caching so page loads are faster"

# ✅ Correct:
"As a user, I want dashboard to load in <2 seconds so I can quickly check metrics"
[Engineering decides: Redis, in-memory cache, or other solution]

Related Skills

Last Updated: 2025-10-25 Format Version: 1.0 (Atomic)