| name | user-story-writing |
| description | Master writing effective user stories with INVEST principles, acceptance criteria, story slicing, and agile best practices for clear, testable requirements. |
User Story Writing
Write effective user stories that capture customer value, enable development teams, and ensure clear acceptance criteria for agile delivery.
When to Use This Skill
- Breaking down features into user stories
- Writing clear requirements for development
- Defining acceptance criteria
- Creating testable stories
- Estimating story complexity
- Facilitating backlog refinement
- Communicating with stakeholders
- Planning sprints and releases
Core Concepts
1. User Story Format
Standard Format:
As a [type of user],
I want [an action or feature],
So that [a benefit or value].
Example:
As a customer,
I want to save items to a wishlist,
So that I can purchase them later.
2. INVEST Principles
- Independent: Stories can be developed in any order
- Negotiable: Details can be discussed and refined
- Valuable: Delivers clear value to users or business
- Estimable: Team can estimate effort required
- Small: Can be completed within a sprint
- Testable: Has clear pass/fail criteria
3. Story Components
- Title: Brief, descriptive name
- Description: As a/I want/So that format
- Acceptance Criteria: Specific conditions for completion
- Story Points: Complexity/effort estimate
- Priority: Business value ranking
- Dependencies: Related stories or technical requirements
Practical Patterns
Pattern 1: E-commerce User Stories
## Story 1: Product Search
**As a** shopper
**I want** to search for products by keyword
**So that** I can quickly find items I'm looking for
**Acceptance Criteria:**
- Given I am on the homepage
- When I enter a keyword in the search box
- Then I see relevant product results within 2 seconds
- And results are sorted by relevance
- And I see product image, name, price, and rating
**Story Points:** 5
**Priority:** High
**Dependencies:** Product catalog API
## Story 2: Add to Cart
**As a** shopper
**I want** to add products to my shopping cart
**So that** I can purchase multiple items together
**Acceptance Criteria:**
- Given I am viewing a product
- When I click "Add to Cart"
- Then the product is added to my cart
- And I see a confirmation message
- And the cart icon shows updated item count
- And I can continue shopping or proceed to checkout
**Story Points:** 3
**Priority:** High
**Dependencies:** Shopping cart service
Pattern 2: SaaS Application Stories
## Story: User Registration
**As a** new user
**I want** to create an account with email and password
**So that** I can access the platform
**Acceptance Criteria:**
- Given I am on the registration page
- When I enter valid email and password
- Then my account is created
- And I receive a verification email
- And I am redirected to onboarding
**Validation Rules:**
- Email must be valid format
- Password must be 8+ characters
- Password must include uppercase, lowercase, number
- Email must not already exist in system
**Story Points:** 5
**Priority:** Critical
Pattern 3: Job Stories (Alternative Format)
## When [situation], I want to [motivation], so I can [expected outcome]
**Example:**
When I'm reviewing my monthly expenses,
I want to filter transactions by category,
So I can understand where I'm spending the most money.
**Acceptance Criteria:**
- Filter dropdown shows all expense categories
- Selecting a category updates the transaction list
- Total amount updates to show filtered sum
- Can clear filter to show all transactions
Pattern 4: Story Slicing
Large Story (Epic):
As a user, I want a comprehensive dashboard
So that I can monitor all my metrics.
Sliced Stories:
Story 1: As a user, I want to view key metrics (revenue, users)
So that I can see high-level performance.
Story 2: As a user, I want to filter metrics by date range
So that I can analyze specific time periods.
Story 3: As a user, I want to export dashboard data to CSV
So that I can analyze it in Excel.
Story 4: As a user, I want to customize which metrics display
So that I can focus on what matters to me.
Pattern 5: Acceptance Criteria with Gherkin
Feature: User Login
Scenario: Successful login with valid credentials
Given I am on the login page
When I enter valid email "user@example.com"
And I enter valid password "SecurePass123"
And I click the "Login" button
Then I should be redirected to the dashboard
And I should see a welcome message
Scenario: Failed login with invalid password
Given I am on the login page
When I enter valid email "user@example.com"
And I enter invalid password "wrong"
And I click the "Login" button
Then I should see an error message "Invalid credentials"
And I should remain on the login page
Pattern 6: Technical Stories
## Story: API Performance Optimization
**As a** developer
**I want** to optimize the user search API response time
**So that** the application provides a better user experience
**Acceptance Criteria:**
- API response time is reduced to under 200ms (p95)
- Database queries are optimized with proper indexing
- Caching is implemented for frequent searches
- Load testing confirms performance improvement
- No regression in search result accuracy
**Technical Notes:**
- Add indexes on users.email and users.name
- Implement Redis caching with 5-minute TTL
- Use database query optimization tools
**Story Points:** 8
**Priority:** Medium
Pattern 7: Bug Fix Stories
## Story: Fix Checkout Payment Error
**As a** customer
**I want** the payment to process correctly
**So that** I can complete my purchase
**Current Behavior:**
- Payment fails intermittently (10% of transactions)
- Error message: "Payment gateway timeout"
- Occurs during peak hours
**Expected Behavior:**
- Payment succeeds consistently
- Proper error handling with retry logic
- Clear error messages for actual failures
**Acceptance Criteria:**
- Payment success rate increases to >99%
- Timeout increased to 30 seconds
- Retry logic implemented (3 attempts)
- User sees clear status during processing
- Failed payments provide actionable error messages
**Story Points:** 5
**Priority:** Critical
Pattern 8: Non-Functional Requirement Stories
## Story: Improve Page Load Performance
**As a** user
**I want** pages to load quickly
**So that** I have a smooth browsing experience
**Acceptance Criteria:**
- Homepage loads in under 2 seconds (p90)
- Largest Contentful Paint (LCP) under 2.5s
- First Input Delay (FID) under 100ms
- Cumulative Layout Shift (CLS) under 0.1
- Performance measured with Lighthouse
- Improvements verified on mobile and desktop
**Implementation:**
- Lazy load images
- Minify CSS and JavaScript
- Implement code splitting
- Use CDN for static assets
**Story Points:** 8
**Priority:** High
Best Practices
Story Writing
- Focus on value - Every story delivers user/business value
- Keep stories small - Completable within one sprint
- Write from user perspective - Emphasize who and why
- Include acceptance criteria - Clear, testable conditions
- Make stories independent - Minimize dependencies
- Use consistent format - Team agreement on structure
- Refine collaboratively - Involve team in refinement
- Estimate relative size - Use story points, not hours
Acceptance Criteria
- Be specific - Clear, unambiguous conditions
- Make testable - Can verify pass/fail
- Cover edge cases - Include error scenarios
- Use Gherkin when helpful - Given/When/Then format
- Define done - What complete means
- Include NFRs - Performance, security, accessibility
- Get team agreement - Shared understanding
- Review before sprint - Ensure clarity
Common Pitfalls to Avoid
- Writing technical tasks instead of user stories
- Stories too large (spanning multiple sprints)
- Vague acceptance criteria
- Missing the "so that" (value statement)
- No user perspective
- Implementation details in stories
- Forgetting edge cases
- Not testable
Tools and Templates
Story Template
## [Story Title]
**As a** [user type]
**I want** [action/feature]
**So that** [benefit/value]
**Acceptance Criteria:**
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
**Story Points:** [1, 2, 3, 5, 8, 13]
**Priority:** [Critical, High, Medium, Low]
**Dependencies:** [List any dependencies]
**Notes:** [Additional context]
Epic Template
## Epic: [Epic Name]
**Goal:** [What we want to achieve]
**Success Metrics:** [How we measure success]
**User Stories:**
1. Story 1 - [Brief description]
2. Story 2 - [Brief description]
3. Story 3 - [Brief description]
**Timeline:** [Target quarter/release]
**Business Value:** [Why this matters]
Resources
