Initial commit
This commit is contained in:
Zhongwei Li
667
skills/prd-generator/references/user_story_examples.md
Normal file
667
skills/prd-generator/references/user_story_examples.md
Normal file
@@ -0,0 +1,667 @@
|
||||
# User Story Examples & Best Practices
|
||||
|
||||
A comprehensive guide to writing effective user stories with real-world examples across different domains.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [User Story Format](#user-story-format)
|
||||
2. [Anatomy of Good User Stories](#anatomy-of-good-user-stories)
|
||||
3. [Examples by Domain](#examples-by-domain)
|
||||
4. [Acceptance Criteria Patterns](#acceptance-criteria-patterns)
|
||||
5. [Common Mistakes](#common-mistakes)
|
||||
6. [Story Splitting](#story-splitting)
|
||||
|
||||
---
|
||||
|
||||
## User Story Format
|
||||
|
||||
### Standard Template
|
||||
|
||||
```
|
||||
As a [user type/persona],
|
||||
I want to [perform action/use feature],
|
||||
So that [achieve benefit/value].
|
||||
```
|
||||
|
||||
### Alternative Formats
|
||||
|
||||
**Job Story (Jobs-to-be-Done):**
|
||||
```
|
||||
When [situation],
|
||||
I want to [motivation],
|
||||
So I can [expected outcome].
|
||||
```
|
||||
|
||||
**Feature-Driven:**
|
||||
```
|
||||
In order to [receive benefit],
|
||||
As a [user type],
|
||||
I want [feature/capability].
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Anatomy of Good User Stories
|
||||
|
||||
### INVEST Criteria
|
||||
|
||||
Good user stories are:
|
||||
|
||||
- **Independent:** Can be developed and delivered separately
|
||||
- **Negotiable:** Details can be discussed and adjusted
|
||||
- **Valuable:** Delivers clear value to users or business
|
||||
- **Estimable:** Can be sized/estimated by the team
|
||||
- **Small:** Can be completed in one iteration/sprint
|
||||
- **Testable:** Has clear acceptance criteria
|
||||
|
||||
### Key Components
|
||||
|
||||
1. **User Type:** Who is the user? Be specific.
|
||||
2. **Action:** What do they want to do? One clear action.
|
||||
3. **Value:** Why do they want it? The benefit or outcome.
|
||||
4. **Acceptance Criteria:** How do we know it's done? Testable conditions.
|
||||
|
||||
---
|
||||
|
||||
## Examples by Domain
|
||||
|
||||
### E-Commerce
|
||||
|
||||
#### Example 1: Product Search
|
||||
|
||||
**User Story:**
|
||||
```
|
||||
As a online shopper,
|
||||
I want to filter products by price range,
|
||||
So that I can find items within my budget.
|
||||
```
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Given I'm on the product listing page, when I set a minimum and maximum price, then only products within that range are displayed
|
||||
- [ ] Given I've applied a price filter, when I clear the filter, then all products are shown again
|
||||
- [ ] Given I set an invalid price range (min > max), when I apply the filter, then I see an error message
|
||||
- [ ] Price filter persists when I navigate between pages of results
|
||||
- [ ] Filter displays count of products matching the criteria
|
||||
|
||||
**Priority:** Must Have (P0)
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
#### Example 2: Guest Checkout
|
||||
|
||||
**User Story:**
|
||||
```
|
||||
As a first-time customer,
|
||||
I want to checkout without creating an account,
|
||||
So that I can complete my purchase quickly.
|
||||
```
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Given I have items in cart, when I click checkout, then I see options for "Guest Checkout" and "Sign In"
|
||||
- [ ] Given I choose guest checkout, when I enter shipping and payment info, then I can complete the order
|
||||
- [ ] Given I complete a guest checkout, when the order is placed, then I receive a confirmation email
|
||||
- [ ] After guest checkout, I see an option to create an account with my order information
|
||||
- [ ] Guest checkout flow takes no more than 3 screens
|
||||
|
||||
**Priority:** Must Have (P0)
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
### SaaS / B2B Platform
|
||||
|
||||
#### Example 3: Team Collaboration
|
||||
|
||||
**User Story:**
|
||||
```
|
||||
As a project manager,
|
||||
I want to assign tasks to team members,
|
||||
So that everyone knows their responsibilities.
|
||||
```
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Given I'm viewing a task, when I click "Assign", then I see a list of team members
|
||||
- [ ] Given I select a team member, when I confirm the assignment, then they receive a notification
|
||||
- [ ] Given a task is assigned, when I view the task list, then I can see who is assigned to each task
|
||||
- [ ] Given I'm a team member, when I'm assigned a task, then it appears in my "My Tasks" view
|
||||
- [ ] I can assign multiple people to a single task
|
||||
- [ ] I can change or remove task assignments
|
||||
|
||||
**Priority:** Must Have (P0)
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
#### Example 4: Usage Analytics
|
||||
|
||||
**User Story:**
|
||||
```
|
||||
As a SaaS administrator,
|
||||
I want to view team usage analytics,
|
||||
So that I can optimize our subscription plan.
|
||||
```
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Given I have admin permissions, when I navigate to analytics, then I see usage metrics for the last 30 days
|
||||
- [ ] Dashboard shows: active users, feature usage, API calls, and storage used
|
||||
- [ ] Given I select a date range, when I apply the filter, then metrics update accordingly
|
||||
- [ ] I can export analytics data as CSV
|
||||
- [ ] Metrics update in real-time (max 5-minute delay)
|
||||
|
||||
**Priority:** Should Have (P1)
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
### Mobile App
|
||||
|
||||
#### Example 5: Push Notifications
|
||||
|
||||
**User Story:**
|
||||
```
|
||||
As a mobile app user,
|
||||
I want to customize which notifications I receive,
|
||||
So that I only see relevant updates.
|
||||
```
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Given I'm in settings, when I navigate to notifications, then I see toggle switches for each notification type
|
||||
- [ ] Notification types include: messages, mentions, updates, promotions
|
||||
- [ ] Given I disable a notification type, when that event occurs, then I don't receive a push notification
|
||||
- [ ] Settings sync across devices using the same account
|
||||
- [ ] Default settings are: messages ON, mentions ON, updates ON, promotions OFF
|
||||
|
||||
**Priority:** Must Have (P0)
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
#### Example 6: Offline Mode
|
||||
|
||||
**User Story:**
|
||||
```
|
||||
As a mobile user with unreliable connectivity,
|
||||
I want to access my recently viewed content offline,
|
||||
So that I can continue using the app without internet.
|
||||
```
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Given I've viewed content while online, when I go offline, then I can still access the last 50 items viewed
|
||||
- [ ] Given I'm offline, when I try to access new content, then I see a "No connection" message with cached content
|
||||
- [ ] Given I'm offline and make changes, when I reconnect, then changes sync automatically
|
||||
- [ ] Offline indicator appears in the app when connectivity is lost
|
||||
- [ ] Cached content is automatically cleared after 7 days
|
||||
|
||||
**Priority:** Should Have (P1)
|
||||
**Story Points:** 13
|
||||
|
||||
---
|
||||
|
||||
### Authentication & Security
|
||||
|
||||
#### Example 7: Two-Factor Authentication
|
||||
|
||||
**User Story:**
|
||||
```
|
||||
As a security-conscious user,
|
||||
I want to enable two-factor authentication,
|
||||
So that my account is protected from unauthorized access.
|
||||
```
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Given I'm in security settings, when I enable 2FA, then I can choose between SMS and authenticator app
|
||||
- [ ] Given I choose authenticator app, when I scan the QR code, then I must enter a verification code to activate
|
||||
- [ ] Given 2FA is enabled, when I log in, then I'm prompted for my second factor
|
||||
- [ ] I receive backup codes when activating 2FA
|
||||
- [ ] I can disable 2FA with my current password + 2FA code
|
||||
|
||||
**Priority:** Must Have (P0)
|
||||
**Story Points:** 13
|
||||
|
||||
---
|
||||
|
||||
#### Example 8: Password Reset
|
||||
|
||||
**User Story:**
|
||||
```
|
||||
As a user who forgot my password,
|
||||
I want to reset it via email,
|
||||
So that I can regain access to my account.
|
||||
```
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Given I click "Forgot Password", when I enter my email, then I receive a reset link within 5 minutes
|
||||
- [ ] Reset link expires after 24 hours
|
||||
- [ ] Given I click the reset link, when I enter a new password, then it must meet password requirements (shown on screen)
|
||||
- [ ] After successful reset, I'm logged in automatically
|
||||
- [ ] If email doesn't exist in system, show generic message (don't reveal if account exists)
|
||||
|
||||
**Priority:** Must Have (P0)
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
### Content & Media
|
||||
|
||||
#### Example 9: Video Upload
|
||||
|
||||
**User Story:**
|
||||
```
|
||||
As a content creator,
|
||||
I want to upload videos with progress tracking,
|
||||
So that I know when my upload is complete.
|
||||
```
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Given I select a video file, when I click upload, then I see a progress bar showing percentage complete
|
||||
- [ ] Supported formats: MP4, MOV, AVI (max 2GB)
|
||||
- [ ] Given upload is in progress, when I navigate away, then upload continues in background
|
||||
- [ ] Given upload completes, when processing is done, then I receive a notification
|
||||
- [ ] Given upload fails, when error occurs, then I see specific error message and can retry
|
||||
|
||||
**Priority:** Must Have (P0)
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
### Admin & Configuration
|
||||
|
||||
#### Example 10: User Permissions
|
||||
|
||||
**User Story:**
|
||||
```
|
||||
As an administrator,
|
||||
I want to assign role-based permissions to users,
|
||||
So that team members have appropriate access levels.
|
||||
```
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Given I'm viewing a user profile, when I click "Change Role", then I see available roles: Admin, Editor, Viewer
|
||||
- [ ] Given I assign a role, when I save, then user immediately gains/loses associated permissions
|
||||
- [ ] Admin: full access; Editor: create/edit content; Viewer: read-only
|
||||
- [ ] I can create custom roles with specific permission combinations
|
||||
- [ ] Audit log records all permission changes with timestamp and admin who made the change
|
||||
|
||||
**Priority:** Must Have (P0)
|
||||
**Story Points:** 13
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria Patterns
|
||||
|
||||
### Given-When-Then Format
|
||||
|
||||
Most structured format, excellent for complex logic:
|
||||
|
||||
```
|
||||
Given [initial context/state],
|
||||
When [action/event],
|
||||
Then [expected outcome].
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Given I'm a logged-in user with items in my cart,
|
||||
When I apply a 20% discount code,
|
||||
Then the cart total is reduced by 20% and displays the discount.
|
||||
```
|
||||
|
||||
### Checklist Format
|
||||
|
||||
Simpler, good for straightforward requirements:
|
||||
|
||||
```
|
||||
- [ ] Requirement 1
|
||||
- [ ] Requirement 2
|
||||
- [ ] Edge case handling
|
||||
```
|
||||
|
||||
### Table Format
|
||||
|
||||
Great for multiple scenarios:
|
||||
|
||||
| Condition | Action | Expected Result |
|
||||
|-----------|--------|----------------|
|
||||
| Valid email | Click "Send" | Confirmation message |
|
||||
| Invalid email | Click "Send" | Error message |
|
||||
| Empty field | Click "Send" | "Required field" error |
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### ❌ Too Technical
|
||||
|
||||
**Bad:**
|
||||
```
|
||||
As a user,
|
||||
I want the system to use Redis caching with 10-minute TTL,
|
||||
So that page loads are fast.
|
||||
```
|
||||
|
||||
**Good:**
|
||||
```
|
||||
As a user,
|
||||
I want pages to load in under 2 seconds,
|
||||
So that I can browse efficiently.
|
||||
```
|
||||
|
||||
**Why:** User stories focus on user value, not implementation. Let engineers choose the solution.
|
||||
|
||||
---
|
||||
|
||||
### ❌ Too Vague
|
||||
|
||||
**Bad:**
|
||||
```
|
||||
As a user,
|
||||
I want the app to be fast,
|
||||
So that I have a good experience.
|
||||
```
|
||||
|
||||
**Good:**
|
||||
```
|
||||
As a user,
|
||||
I want search results to appear in under 1 second,
|
||||
So that I can quickly find what I need.
|
||||
```
|
||||
|
||||
**Why:** "Fast" is subjective. Be specific and measurable.
|
||||
|
||||
---
|
||||
|
||||
### ❌ Missing the "Why"
|
||||
|
||||
**Bad:**
|
||||
```
|
||||
As a user,
|
||||
I want to upload profile pictures.
|
||||
```
|
||||
|
||||
**Good:**
|
||||
```
|
||||
As a user,
|
||||
I want to upload a profile picture,
|
||||
So that other users can recognize me in the community.
|
||||
```
|
||||
|
||||
**Why:** Understanding the "why" helps the team make better decisions.
|
||||
|
||||
---
|
||||
|
||||
### ❌ Multiple Actions in One Story
|
||||
|
||||
**Bad:**
|
||||
```
|
||||
As a user,
|
||||
I want to create an account, set up my profile, and invite team members,
|
||||
So that I can start using the platform.
|
||||
```
|
||||
|
||||
**Good:** Split into three stories:
|
||||
```
|
||||
Story 1: As a user, I want to create an account...
|
||||
Story 2: As a user, I want to set up my profile...
|
||||
Story 3: As an account owner, I want to invite team members...
|
||||
```
|
||||
|
||||
**Why:** Stories should be small and focused on one capability.
|
||||
|
||||
---
|
||||
|
||||
### ❌ No Acceptance Criteria
|
||||
|
||||
**Bad:**
|
||||
```
|
||||
As a user,
|
||||
I want to search for products,
|
||||
So that I can find what I need.
|
||||
```
|
||||
|
||||
**Good:** Add specific criteria:
|
||||
```
|
||||
Acceptance Criteria:
|
||||
- [ ] Search works on product name and description
|
||||
- [ ] Results display in under 2 seconds
|
||||
- [ ] Displays "No results found" when no matches
|
||||
- [ ] Shows top 20 results with pagination
|
||||
```
|
||||
|
||||
**Why:** Acceptance criteria define "done" and enable testing.
|
||||
|
||||
---
|
||||
|
||||
## Story Splitting Techniques
|
||||
|
||||
When a story is too large, use these techniques to split it:
|
||||
|
||||
### 1. By Workflow Steps
|
||||
|
||||
**Large Story:**
|
||||
```
|
||||
As a user, I want to book a flight online.
|
||||
```
|
||||
|
||||
**Split Stories:**
|
||||
- Search for flights
|
||||
- Select flight
|
||||
- Enter passenger details
|
||||
- Choose seat
|
||||
- Make payment
|
||||
- Receive confirmation
|
||||
|
||||
---
|
||||
|
||||
### 2. By User Persona
|
||||
|
||||
**Large Story:**
|
||||
```
|
||||
As a user, I want to manage my subscriptions.
|
||||
```
|
||||
|
||||
**Split Stories:**
|
||||
- As a free user, I want to view available plans
|
||||
- As a paid user, I want to upgrade my plan
|
||||
- As an admin, I want to manage team subscriptions
|
||||
|
||||
---
|
||||
|
||||
### 3. By Business Rules
|
||||
|
||||
**Large Story:**
|
||||
```
|
||||
As a user, I want to apply discount codes.
|
||||
```
|
||||
|
||||
**Split Stories:**
|
||||
- Apply percentage discount (e.g., 20% off)
|
||||
- Apply fixed amount discount (e.g., $10 off)
|
||||
- Apply free shipping discount
|
||||
- Handle expired discount codes
|
||||
- Limit one discount per order
|
||||
|
||||
---
|
||||
|
||||
### 4. By Data Variations
|
||||
|
||||
**Large Story:**
|
||||
```
|
||||
As a user, I want to import contacts.
|
||||
```
|
||||
|
||||
**Split Stories:**
|
||||
- Import from CSV file
|
||||
- Import from Google Contacts
|
||||
- Import from Microsoft Outlook
|
||||
- Import from LinkedIn
|
||||
|
||||
---
|
||||
|
||||
### 5. By CRUD Operations
|
||||
|
||||
**Large Story:**
|
||||
```
|
||||
As a user, I want to manage my projects.
|
||||
```
|
||||
|
||||
**Split Stories:**
|
||||
- Create a new project
|
||||
- View project details
|
||||
- Update project settings
|
||||
- Delete a project
|
||||
|
||||
---
|
||||
|
||||
### 6. By Happy Path / Edge Cases
|
||||
|
||||
**MVP Story (Happy Path):**
|
||||
```
|
||||
As a user, I want to upload a profile photo (JPG, < 5MB).
|
||||
```
|
||||
|
||||
**Follow-up Stories:**
|
||||
- Support additional formats (PNG, GIF)
|
||||
- Handle files larger than 5MB with error message
|
||||
- Auto-crop/resize images
|
||||
- Allow photo deletion
|
||||
|
||||
---
|
||||
|
||||
## Story Sizing Guidelines
|
||||
|
||||
### Story Points Reference
|
||||
|
||||
**1-2 Points (Few hours):**
|
||||
- Simple UI change
|
||||
- Copy update
|
||||
- Minor configuration
|
||||
|
||||
**3-5 Points (1-2 days):**
|
||||
- New form with validation
|
||||
- Simple API endpoint
|
||||
- Basic feature toggle
|
||||
|
||||
**8 Points (3-5 days):**
|
||||
- Complex form with business logic
|
||||
- Integration with third-party service
|
||||
- New database schema with migration
|
||||
|
||||
**13+ Points (1+ weeks):**
|
||||
- Too large! Split the story
|
||||
- Consider as an Epic
|
||||
|
||||
---
|
||||
|
||||
## Templates for Common Scenarios
|
||||
|
||||
### Registration/Sign-Up
|
||||
|
||||
```
|
||||
As a new visitor,
|
||||
I want to create an account with my email,
|
||||
So that I can access personalized features.
|
||||
|
||||
Acceptance Criteria:
|
||||
- [ ] Email and password required (password: min 8 chars, 1 number, 1 special char)
|
||||
- [ ] Email validation and duplicate check
|
||||
- [ ] Confirmation email sent upon registration
|
||||
- [ ] Automatically logged in after email confirmation
|
||||
- [ ] Option to sign up with Google/Apple (social auth)
|
||||
```
|
||||
|
||||
### Data Export
|
||||
|
||||
```
|
||||
As a user,
|
||||
I want to export my data as CSV,
|
||||
So that I can analyze it in Excel.
|
||||
|
||||
Acceptance Criteria:
|
||||
- [ ] Export button in settings
|
||||
- [ ] Includes all user data (specify fields)
|
||||
- [ ] File downloads immediately (or email if > 10MB)
|
||||
- [ ] Filename format: "export_[username]_[date].csv"
|
||||
- [ ] Respects data privacy regulations (only user's own data)
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
```
|
||||
As a user,
|
||||
I want to see helpful error messages,
|
||||
So that I know how to fix issues.
|
||||
|
||||
Acceptance Criteria:
|
||||
- [ ] Error messages are specific (not generic "Error occurred")
|
||||
- [ ] Suggest actionable next steps
|
||||
- [ ] Display in user's language
|
||||
- [ ] Don't expose technical details (stack traces)
|
||||
- [ ] Log errors for debugging (backend)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
1. **Write from user perspective**, not system perspective
|
||||
2. **Focus on value/benefit**, not just functionality
|
||||
3. **Keep stories small** (completable in one sprint)
|
||||
4. **Make acceptance criteria testable**
|
||||
5. **Use consistent format** across your team
|
||||
6. **Include edge cases** in acceptance criteria
|
||||
7. **Collaborate** with engineers and designers when writing
|
||||
8. **Refine regularly** based on new learnings
|
||||
9. **Link to mockups/designs** when relevant
|
||||
10. **Prioritize ruthlessly** (must/should/nice-to-have)
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
### User Story Template
|
||||
|
||||
```
|
||||
Title: [Concise feature name]
|
||||
|
||||
As a [specific user type],
|
||||
I want to [action/capability],
|
||||
So that [benefit/value].
|
||||
|
||||
Acceptance Criteria:
|
||||
- [ ] [Testable criterion 1]
|
||||
- [ ] [Testable criterion 2]
|
||||
- [ ] [Edge case handling]
|
||||
|
||||
Priority: [Must Have / Should Have / Nice to Have]
|
||||
Story Points: [1/2/3/5/8/13]
|
||||
Dependencies: [List if any]
|
||||
Design: [Link to mockups]
|
||||
Notes: [Additional context]
|
||||
```
|
||||
|
||||
### Epic vs Story vs Task
|
||||
|
||||
**Epic:** Large body of work (multiple sprints)
|
||||
- Example: "User Authentication System"
|
||||
|
||||
**Story:** Deliverable value (one sprint)
|
||||
- Example: "As a user, I want to reset my password..."
|
||||
|
||||
**Task:** Implementation step (hours/days)
|
||||
- Example: "Create password reset API endpoint"
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
Effective user stories:
|
||||
- Start with the user's perspective
|
||||
- Clearly articulate value
|
||||
- Include testable acceptance criteria
|
||||
- Are sized appropriately
|
||||
- Enable team collaboration
|
||||
|
||||
Use these examples as templates, but adapt them to your product and users' specific needs!
|
||||
Reference in New Issue
Block a user