Functional Requirements - Learning Module

Loading content...

0/273

User Stories and Use Cases

The Language of Requirements

Every software disaster has a moment where, in retrospect, someone should have asked: 'But what exactly does the user need to do?'

The gap between stakeholder intent and delivered software is bridged—or widened—by how requirements are captured and communicated. Two techniques have emerged as industry standards for this critical translation: user stories and use cases. While often mentioned together, they serve fundamentally different purposes and excel in different contexts.

User stories, born from Agile methodologies, capture the intent of software functionality from the user's perspective in a brief, conversational format. Use cases, with roots in UML and structured analysis, capture the complete behavioral specification of how systems respond to user interactions, including all variations and exceptions.

Mastering both—and knowing when to apply each—is a hallmark of Principal Engineers who ensure that what gets built is precisely what was needed.

What You Will Master

By the end of this page, you will understand: (1) the anatomy and purpose of user stories, (2) how to write effective acceptance criteria, (3) the complete structure of use cases, (4) when to use stories vs. use cases, (5) how these techniques complement each other in system design, and (6) patterns for ensuring complete requirement coverage.

User Stories: The Agile Standard

User stories revolutionized how software teams think about requirements. Instead of lengthy specification documents that nobody reads, user stories capture requirements as short narratives that describe what someone wants to accomplish.

The Standard Format:

The canonical user story format is:

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

This simple template encodes three critical pieces of information:

Who — The persona or role that wants this capability
What — The action or capability they want
Why — The underlying need or value they're seeking

The 'why' is often the most neglected part, yet it's frequently the most valuable. Understanding why users want something reveals whether you're solving the right problem.

User Story Quality Comparison
Quality Level	User Story	Problem
Poor	As a user, I want to search.	Who is 'a user'? Search what? Search how? Why?
Mediocre	As a customer, I want to search for products.	No 'why' clause. What kind of search? By name? Category?
Good	As a customer, I want to search for products by name, so that I can quickly find items I already know about.	Clear who, what, and why. Implies text search.
Excellent	As a returning customer, I want to search for products by partial name matching, so that I can find items even when I don't remember the exact product name.	Specific persona, detailed behavior, clear value proposition.

Why User Stories Work:

User stories succeed because they:

Force user-centricity — By starting with 'As a [user],' stories prevent solution-first thinking
Enable conversation — Stories are intentionally brief; the detail comes from discussion, not documentation
Scale to complexity — Large features become 'epics' containing smaller stories
Support estimation — Teams can estimate relative effort on consistently-sized stories
Defer design decisions — Stories describe outcomes, not implementations

The Conversation Principle:

Ron Jeffries, one of Agile's founders, described user stories with the '3 Cs':

Card — The story itself, brief enough to fit on an index card
Conversation — Discussions between stakeholders and team to clarify details
Confirmation — Acceptance criteria that confirm when the story is done

The story is a placeholder for a conversation, not a replacement for one. Engineers who demand complete specifications in story format miss the point entirely.

Stories Are Negotiable

Unlike traditional requirements that are 'locked in,' user stories are designed to be negotiated. The team and stakeholders discuss the story, explore alternatives, and evolve understanding. A story that can't be negotiated should probably be a constraint or a use case instead.

Anatomy of Excellent User Stories

Writing good user stories is a skill that separates effective teams from those constantly reworking misunderstood requirements. The INVEST criteria provide a checklist for story quality:

The INVEST Criteria

•I - Independent — The story can be developed and delivered without depending on other uncompleted stories. Dependencies create bottlenecks and reduce team flexibility.
•N - Negotiable — Details can be discussed and adjusted. Stories that are over-specified remove the team's ability to find the best solution.
•V - Valuable — The story delivers value to someone. Technical tasks ('refactor the OrderService') aren't user stories—they enable stories but aren't stories themselves.
•E - Estimable — The team can estimate the story's complexity. If they can't, the story is too vague or too large; split or clarify it.
•S - Small — The story can be completed within one iteration. Large stories carry too much risk and delay feedback.
•T - Testable — There's an objective way to determine if the story is complete. If you can't test it, you can't know when you're done.

Story Splitting Strategies:

When stories are too large, Principal Engineers apply these splitting patterns:

Story Splitting Patterns
Pattern	Description	Example (Payment Feature)
By User Type	Split by different users who need the feature differently	Credit card payment for new customers → registered customers → guest checkout
By Workflow Steps	Split by steps in a process	Enter card details → Validate card → Process payment → Handle errors
By Business Rules	Split by variations in business logic	Standard payment → Promotional code payment → Gift card payment
By Data Variations	Split by different data handling	Single currency → Multi-currency → Currency conversion
By Interface Type	Split by different access methods	Web checkout → Mobile checkout → API checkout
By Operations (CRUD)	Split by create/read/update/delete	Add payment method → View saved methods → Edit method → Delete method
By Happy Path vs. Edge Cases	Separate main flow from exceptions	Successful payment → Failed payment → Timeout handling → Duplicate prevention
By Performance Characteristics	Split by different performance needs	Standard checkout → High-volume flash sale → Bulk order processing

story-splitting.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
# Epic: Payment Processing
 
## Before Splitting (Too Large)
As a customer, I want to pay for my order using various payment methods
so that I can complete my purchase in my preferred way.
 
PROBLEM: This epic is too vague and too large. It can't be estimated,
and "various payment methods" hides massive complexity.
 
## After Splitting (Independently Deliverable)
 
### Story 1: Credit Card Payment (Core Path)
As a customer, I want to pay for my order using my credit card,
so that I can complete my purchase using my most common payment method.
 
Acceptance Criteria:
- Customer can enter Visa or Mastercard details
- Card validation occurs before submission
- Successful payment shows confirmation
- Failed payment shows clear error message
 
### Story 2: Saved Payment Methods
As a returning customer, I want to pay using a previously saved card,
so that I don't have to re-enter my card details every time.
 
Acceptance Criteria:
- Customer sees list of saved cards (last 4 digits + expiry)
- One-click payment with saved card
- Option to use new card instead
- Requires re-authentication for security
 
### Story 3: PayPal Integration
As a customer who prefers PayPal, I want to pay using my PayPal account,
so that I don't have to share card details with this site.
 
Acceptance Criteria:
- PayPal option visible at checkout
- Redirects to PayPal for authentication
- Returns to site with payment confirmation
- Handles PayPal cancellation gracefully
 
### Story 4: Payment Error Handling
As a customer whose payment failed, I want to understand why and retry,
so that I can complete my purchase without starting over.
 
Acceptance Criteria:
- Clear error messages (not technical codes)
- Cart and entered data preserved on error
- Retry button available
- Alternative payment suggestion after 2 failures
 
RESULT: Four independently deliverable stories, each estimable and testable.
The team can deliver value with just Story 1 and iterate.

Don't Split Vertically

A common anti-pattern is splitting by technical layer: 'Create payment API' → 'Create payment UI' → 'Create payment database.' These slices are not independently valuable—a database without UI delivers nothing. Always split so each piece delivers end-to-end value, even if limited.

Acceptance Criteria: Defining 'Done'

While user stories describe what users want, acceptance criteria define how we know we've delivered it. They are the contract between the team and stakeholders, transforming subjective 'is this good enough?' conversations into objective 'did we meet the criteria?' verification.

Two Formats for Acceptance Criteria:

The two most common formats are the checklist format and the Given-When-Then (Gherkin) format.

Checklist Format

Simple, bulleted conditions that must be true:

✓ User can select date from calendar ✓ Dates in the past are disabled ✓ Selected date displays in header ✓ Time zone is displayed ✓ 'Today' button returns to current date

Best for: Simple features, quick verification, less formal environments

Given-When-Then (Gherkin) Format

Structured scenarios with preconditions, actions, and outcomes:

Given I am on the checkout page
And I have items in my cart
When I click 'Select Delivery Date'
Then a calendar popup appears
And past dates are disabled
And the current date is highlighted

Best for: Complex flows, automated testing, precise behavior specification

The Gherkin Format Deep Dive:

Gherkin syntax (used by tools like Cucumber, Behave, and SpecFlow) provides a structured language for acceptance criteria that can be directly executed as automated tests.

Key Components:

Given — The context/precondition before the action
When — The action the user takes
Then — The expected outcome
And — Continues the previous statement type
But — Negative continuation for Then statements

login-scenarios.feature
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
Feature: User Login
  As a registered user
  I want to log into my account
  So that I can access my personalized dashboard
 
  Background:
    Given the login page is displayed
    And the authentication service is operational
 
  Scenario: Successful login with valid credentials
    Given I am a registered user with email "user@example.com"
    When I enter email "user@example.com"
    And I enter password "correctPassword123"
    And I click the "Log In" button
    Then I should be redirected to the dashboard
    And I should see "Welcome back, User" in the header
    And my last login time should be updated
 
  Scenario: Failed login with incorrect password
    Given I am a registered user with email "user@example.com"
    When I enter email "user@example.com"
    And I enter password "wrongPassword"
    And I click the "Log In" button
    Then I should remain on the login page
    And I should see error message "Invalid email or password"
    And the password field should be cleared
    But the email field should retain my entered email
 
  Scenario: Account lockout after multiple failed attempts
    Given I am a registered user with email "user@example.com"
    And I have 4 previous failed login attempts
    When I enter email "user@example.com"
    And I enter password "wrongPassword"
    And I click the "Log In" button
    Then I should see error message "Account locked. Please try again in 15 minutes."
    And I should receive a security alert email
    And the account should be locked for 15 minutes
 
  Scenario Outline: Input validation
    When I enter email "<email>"
    And I enter password "<password>"
    And I click the "Log In" button
    Then I should see error message "<error_message>"
 
    Examples:
      | email              | password | error_message                    |
      |                    | pass123  | Email is required                |
      | user@example.com   |          | Password is required             |
      | invalid-email      | pass123  | Please enter a valid email       |
      | user@example.com   | 123      | Password must be at least 8 chars|

Acceptance Criteria Best Practices:

Writing Effective Acceptance Criteria

•Be specific enough to test — 'System responds quickly' is untestable. 'System responds in under 200ms' is testable.
•Be general enough to allow solutions — Don't specify implementation. 'A dropdown appears' dictates UI; 'user can select from options' allows flexibility.
•Cover the happy path first — Don't get lost in edge cases before defining the main flow.
•Include error scenarios — What happens when things go wrong is often more important than when they go right.
•Limit to 8-12 criteria per story — More than this suggests the story needs splitting.
•Involve the whole team — Developers, testers, and stakeholders should collaborate on acceptance criteria, not just product owners.
•Review and refine — Criteria should evolve through conversation, not be handed down as edicts.

Acceptance Criteria Are a Contract

Well-written acceptance criteria protect both the team and stakeholders. The team knows exactly what 'done' means, preventing scope creep during development. Stakeholders have verifiable guarantees about what they'll receive. Ambiguous criteria lead to 'that's not what I meant' moments at demo time.

Use Cases: The Complete Specification

While user stories excel at capturing intent and enabling conversation, use cases provide comprehensive behavioral specifications. Originating from UML (Unified Modeling Language), use cases describe complete interactions between actors (users or systems) and the system being designed.

When Use Cases Shine:

Complex workflows with many steps
Systems with extensive exception handling
Safety-critical or regulated domains
Integration specifications between systems
Formal documentation requirements
Training documentation needs

Use Case Structure:

A complete use case document contains these elements:

Use Case Document Structure
Element	Description	Example
Name	Brief, action-oriented title	Place Order
ID	Unique identifier for reference	UC-ORD-001
Description	One-paragraph summary	Allows customer to purchase items in cart
Actors	Who/what interacts with the system	Primary: Customer, Secondary: Payment Gateway
Preconditions	What must be true before starting	Customer logged in, Cart has items
Postconditions	What is true after completion	Order created, Payment captured, Inventory updated
Main Flow	Step-by-step normal scenario	Customer selects checkout...
Alternative Flows	Variations in the happy path	3a. Guest checkout selected...
Exception Flows	Error handling paths	6x. Payment declined...
Business Rules	Rules governing behavior	Orders over $100 require verification
Frequency	How often this occurs	~10,000/day
Priority	Importance ranking	Critical

use-case-place-order.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
# Use Case: Place Order (UC-ORD-001)
 
## Description
Enables a customer to complete the purchase of items in their shopping cart,
processing payment and initiating order fulfillment.
 
## Primary Actor
Customer (authenticated or guest)
 
## Secondary Actors
- Payment Gateway (Stripe)
- Inventory System
- Notification Service
- Fraud Detection Service
 
## Stakeholders and Interests
- Customer: Wants fast, secure checkout with clear confirmation
- Business: Wants completed sale, accurate inventory, fraud prevention
- Fulfillment: Wants accurate order details for shipping
- Finance: Wants accurate transaction records for reconciliation
 
## Preconditions
- Customer has at least one item in shopping cart
- All cart items are available in inventory (checked at cart level)
- System is operational and connected to payment gateway
 
## Postconditions (Success)
- Order record created with unique order ID
- Payment authorized and captured
- Inventory reserved/decremented
- Confirmation email sent to customer
- Order visible in customer's order history
- Order queued for fulfillment processing
 
## Postconditions (Failure)
- No order created
- No payment captured
- Customer notified of issue with suggested action
- Cart preserved in original state
- Failed attempt logged for analysis
 
## Main Success Scenario (Basic Flow)
 
| Step | Actor    | System Response                                   |
|------|----------|---------------------------------------------------|
| 1    | Customer | Clicks "Checkout" button                          |
| 2    |          | Validates cart (inventory, prices, promotions)    |
| 3    |          | Displays order summary with totals                |
| 4    | Customer | Enters/confirms shipping address                  |
| 5    |          | Calculates shipping options and costs             |
| 6    | Customer | Selects shipping method                           |
| 7    |          | Updates order total with shipping                 |
| 8    | Customer | Enters payment information                        |
| 9    |          | Validates payment info format                     |
| 10   |          | Submits to fraud detection (async)                |
| 11   |          | Submits to payment gateway for authorization      |
| 12   |          | Receives authorization approval                   |
| 13   |          | Creates order record (status: CONFIRMED)          |
| 14   |          | Reserves inventory                                |
| 15   |          | Captures payment (or schedules capture)           |
| 16   |          | Sends confirmation email                          |
| 17   |          | Displays confirmation page with order number      |
 
## Alternative Flows
 
### 4a. Guest Checkout
| Step | Description                                             |
|------|---------------------------------------------------------|
| 4a.1 | Customer proceeds without account                       |
| 4a.2 | System prompts for email (for receipt/tracking)         |
| 4a.3 | Customer enters email                                   |
| 4a.4 | System continues to Step 5                              |
| 4a.5 | Post-order: System offers account creation              |
 
### 6a. Express Shipping Selected
| Step | Description                                             |
|------|---------------------------------------------------------|
| 6a.1 | Customer selects express shipping                       |
| 6a.2 | System verifies delivery address eligibility            |
| 6a.3 | System shows updated delivery estimate                  |
| 6a.4 | System continues to Step 7 with express costs           |
 
### 8a. Saved Payment Method
| Step | Description                                             |
|------|---------------------------------------------------------|
| 8a.1 | Customer selects saved card                             |
| 8a.2 | System prompts for CVV only                             |
| 8a.3 | Customer enters CVV                                     |
| 8a.4 | System continues to Step 9                              |
 
### 16a. Email Delivery Failed
| Step | Description                                             |
|------|---------------------------------------------------------|
| 16a.1| Email service returns failure                           |
| 16a.2| System queues retry (up to 3 attempts)                  |
| 16a.3| System logs for monitoring                              |
| 16a.4| Order proceeds (email failure is non-blocking)          |
 
## Exception Flows
 
### 2x. Cart Validation Failed
| Step | Description                                             |
|------|---------------------------------------------------------|
| 2x.1 | System detects unavailable item or price change         |
| 2x.2 | System displays specific issue to customer              |
| 2x.3 | System offers: remove item, update quantity, or cancel  |
| 2x.4 | Customer modifies cart or cancels                       |
| 2x.5 | If modified, return to Step 2; else end use case        |
 
### 11x. Payment Authorization Timeout
| Step | Description                                             |
|------|---------------------------------------------------------|
| 11x.1| Gateway does not respond within 10 seconds              |
| 11x.2| System retries once after 2 seconds                     |
| 11x.3| If retry fails, show error "temporarily unavailable"    |
| 11x.4| Preserve cart and payment form data                     |
| 11x.5| Log incident for operations review                      |
| 11x.6| End use case                                            |
 
### 12x. Payment Authorization Declined
| Step | Description                                             |
|------|---------------------------------------------------------|
| 12x.1| Gateway returns decline code                            |
| 12x.2| System maps code to user-friendly message               |
| 12x.3| Display: "Payment could not be processed. [reason]"     |
| 12x.4| Offer: Try another card, or contact bank                |
| 12x.5| Log attempt (for fraud pattern detection)               |
| 12x.6| If 3rd failure, suggest contacting support              |
| 12x.7| Return to Step 8                                        |
 
### 14x. Inventory Reservation Failed
| Step | Description                                             |
|------|---------------------------------------------------------|
| 14x.1| Race condition: Item sold out after cart validation     |
| 14x.2| System initiates payment reversal/void                  |
| 14x.3| System notifies customer of unavailable item            |
| 14x.4| System offers: waitlist, alternative items, or cancel   |
| 14x.5| Log for inventory system review                         |
| 14x.6| End use case or return to Step 4 with modified cart     |
 
## Business Rules
- BR-1: Orders over $500 require additional fraud check (manual review)
- BR-2: Free shipping for orders over $75 (before tax)
- BR-3: Maximum 10 of same item per order
- BR-4: Promo codes limited to one per order
- BR-5: Alcohol items require age verification at delivery
- BR-6: International orders require customs declaration
 
## Non-Functional Requirements
- NFR-1: Checkout flow completion under 60 seconds (p95)
- NFR-2: Payment processing latency under 3 seconds (p95)  
- NFR-3: System handles 500 concurrent checkouts
- NFR-4: 99.9% availability during business hours
 
## Frequency of Use
- Average: 10,000 orders/day
- Peak: 50,000 orders/day (Black Friday)
 
## Open Issues
- [ ] Define behavior for split payments (2 cards)
- [ ] Clarify digital goods delivery workflow
- [ ] Confirm tax calculation service selection

Use Cases Document the Complete Behavior

Notice how the use case captures not just the happy path, but every decision point, every exception, and every business rule. This level of detail is what makes use cases invaluable for complex systems where missing an edge case can cause real harm.

Use Case Diagrams and Relationships

Use case diagrams provide a visual overview of system functionality and actor interactions. While the textual use case contains detail, the diagram shows scope and relationships at a glance.

Diagram Elements:

Use Case Diagram Components

•System Boundary — A rectangle showing the system scope; use cases inside, actors outside
•Actor — Stick figure or icon representing a user role or external system
•Use Case — Oval containing the use case name inside the system boundary
•Association — Solid line connecting actor to use case they participate in
•Include — Dashed arrow with <<include>> showing mandatory sub-use case
•Extend — Dashed arrow with <<extend>> showing optional extension
•Generalization — Solid arrow showing actor or use case inheritance

The Three Relationships:

Understanding when to use include, extend, and generalization is crucial for accurate modeling:

Use Case Relationships
Relationship	When to Use	Direction	Example
<<include>>	Base use case ALWAYS requires the included use case	Base → Included	Place Order <<include>> Validate Payment (can't order without validating payment)
<<extend>>	Extension is CONDITIONALLY added to base use case	Extension → Base	Track Order <<extend>> View Live Delivery Map (map only shows during active delivery)
Generalization	Specialized version of actor or use case inherits from general version	Specific → General	Premium Customer → Customer (inherits all customer use cases, adds exclusive ones)

use-case-diagram.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
┌──────────────────────────────────────────────────────────────┐
│                     E-Commerce System                         │
│                                                               │
│                    ┌─────────────────┐                        │
│                    │  Search Products │◄──────────────────────│─── Customer
│                    └─────────────────┘                        │        │
│                    ┌─────────────────┐                        │        │
│    Customer ──────►│  Add to Cart    │                        │        │
│        │          └─────────────────┘                        │        │
│        │           ┌─────────────────┐                        │        │
│        ├──────────►│  View Cart      │                        │        │
│        │          └─────────────────┘                        │        │
│        │           ┌─────────────────┐                        │        ▼
│        ├──────────►│  Place Order    │◄────── <<include>> ────│── Authenticate
│        │          └────────┬────────┘                        │
│        │                    │                                 │
│        │             <<include>>                              │
│        │                    ▼                                 │
│        │           ┌─────────────────┐                        │
│        │          │ Process Payment │◄────────────────────────│─── Payment Gateway
│        │          └─────────────────┘                        │
│        │           ┌─────────────────┐                        │
│        ├──────────►│  Track Order    │◄────── <<extend>> ─────│── View Live Map
│        │          └─────────────────┘                        │
│        │           ┌─────────────────┐                        │
│        └──────────►│ Manage Account  │                        │
│                    └─────────────────┘                        │
│                                                               │
│    Admin ─────────►┌─────────────────┐                        │
│        │          │ Manage Products │                        │
│        │          └─────────────────┘                        │
│        │           ┌─────────────────┐                        │
│        └──────────►│ View Analytics  │                        │
│                    └─────────────────┘                        │
│                                                               │
│    Inventory  ────►┌─────────────────┐                        │
│    System         │ Update Stock    │◄────────────────────────│─── Supplier System
│                    └─────────────────┘                        │
│                                                               │
└──────────────────────────────────────────────────────────────┘
 
LEGEND:
───────►  Association (actor participates in use case)
- - - ->  Include/Extend relationship
- - - ->  Generalization (inheritance)
 
KEY RELATIONSHIPS:
• Place Order <<include>> Process Payment 
  (Every order must process payment - mandatory)
  
• Place Order <<include>> Authenticate
  (Must be authenticated to order - mandatory)
  
• Track Order <<extend>> View Live Map
  (Live map only shown during active delivery - conditional)

Diagrams Are Overviews, Not Specifications

Use case diagrams show what the system does at a glance, but they don't have the detail to drive implementation. Always pair diagrams with full textual use case specifications. The diagram is the map; the specification is the territory.

User Stories vs. Use Cases: When to Use Which

User stories and use cases aren't competitors—they're complementary tools for different contexts. Principal Engineers select the right tool based on the situation.

User Stories vs. Use Cases Comparison
Dimension	User Stories	Use Cases
Origin	Agile/XP methodologies	UML/Structured Analysis
Format	Brief narrative (1-3 sentences)	Structured document (1-5 pages)
Detail Level	Intentionally minimal	Comprehensive
Focus	User intent and value	System behavior and interactions
Conversation	Placeholder for discussion	Record of decisions
Exception Handling	Briefly noted or separate stories	Formally documented in full
Estimation	Easily estimable (story points)	Harder to estimate directly
Testing Input	Acceptance criteria guide testing	Directly translates to test cases
Documentation	Lightweight, may not persist	Formal, persists as system doc
Change Tolerance	Easily changed, expected to evolve	Change requires formal updates

Selection Guidelines:

Use User Stories When...

•Working in Agile/Scrum teams
•Requirements are evolving
•Close collaboration with stakeholders is possible
•Team prefers conversation to documentation
•Features are relatively simple
•Time-to-market is critical
•Team is co-located or highly communicative

Use Use Cases When...

•System has complex workflows
•Formal documentation is required
•Regulatory/compliance needs
•Distributed or outsourced teams
•System integrates many external actors
•Safety-critical applications
•Training documentation is needed

The Hybrid Approach:

Many mature teams use both:

User stories for day-to-day development work
Use cases for complex features or as consolidated documentation

A common pattern:

Epic defined with a use case (complete behavioral spec)
Epic decomposed into user stories for sprint planning
Stories reference the use case for context
After implementation, use case updated as system documentation

hybrid-approach.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
# Hybrid Requirements: Payment Processing
 
## Use Case (Complete Specification)
UC-PAY-001: Process Payment
[Full use case document as shown earlier - 3 pages of detail]
 
## Derived User Stories (For Sprint Planning)
 
### Sprint 14 Stories (derived from UC-PAY-001)
 
**Story 14.1: Credit Card Entry (Points: 3)**
As a customer, I want to enter my credit card details at checkout,
so that I can pay for my order.
AC: See UC-PAY-001, Steps 8-9, Exception 9x
Reference: UC-PAY-001 Main Flow Steps 8-9
 
**Story 14.2: Card Validation (Points: 2)**  
As a customer, I want immediate feedback on card errors,
so that I can correct typos before submitting.
AC: Luhn check, expiry check, format validation
Reference: UC-PAY-001 Step 9
 
**Story 14.3: Payment Gateway Integration (Points: 8)**
As the system, I want to submit payments to Stripe,
so that payments are processed securely.
AC: See UC-PAY-001, Steps 10-12, Exceptions 11x, 12x
Reference: UC-PAY-001 Main Flow Steps 10-12
 
**Story 14.4: Payment Error Handling (Points: 5)**
As a customer whose payment failed, I want to understand why,
so that I can take corrective action.
AC: Map all decline codes, preserve form state, offer retry
Reference: UC-PAY-001 Exception Flow 12x
 
---
 
TRACEABILITY:
- UC-PAY-001 fully covered by Stories 14.1-14.11
- Each story links back to specific use case steps
- Use case serves as authoritative spec; stories are work units
- Post-implementation: UC-PAY-001 updated to reflect reality

Context Determines Choice

There's no universal 'best' approach. Medical device software mandates formal use cases with regulatory traceability. A startup MVP might only need sticky notes with user stories. Principal Engineers adapt their approach to context while maintaining rigor.

Ensuring Complete Requirement Coverage

The most dangerous gaps in requirements aren't the missing features—they're the missing scenarios within features. Principal Engineers use systematic techniques to ensure nothing slips through.

Coverage Techniques:

Systematic Coverage Methods

•User Story Mapping — Visual technique arranging stories by user journey across the top and priority down the side. Reveals gaps between journey steps.
•CRUD Analysis — For each data entity, verify Create, Read, Update, Delete scenarios exist. Missing operations often indicate missing stories.
•State Machine Analysis — For stateful entities, map all states and transitions. Each transition may require a user story.
•Role Matrix — List features vs. user roles. Ensure each role has stories for features they can access.
•Exception Brainstorming — For each happy path, ask 'What if this fails?' systematically at each step.
•External System Mapping — For each integration, document: success, partial failure, complete failure, timeout scenarios.
•Data Lifecycle Review — Trace data from creation to archival: how is it entered, validated, transformed, displayed, reported, archived, deleted?

The Exception Checklist:

For every use case or story, verify these exception categories are addressed:

Exception Categories to Always Consider
Category	Questions to Ask	Example Scenario
Validation Failure	What if input is invalid, missing, or malicious?	User submits empty required field, SQL injection attempt
Authentication Failure	What if user isn't logged in or session expires?	Session timeout during checkout
Authorization Failure	What if user lacks permission?	Regular user tries admin function
Dependency Failure	What if external service is down?	Payment gateway timeout
Concurrency Conflicts	What if another user modified the same data?	Two users edit same record
Resource Exhaustion	What if system runs out of capacity?	Database connection pool exhausted
Business Rule Violation	What if a business constraint is violated?	Order exceeds credit limit
Data Inconsistency	What if data is in an unexpected state?	Order references deleted product
Timeout	What if operation takes too long?	Long-running report generation
Partial Completion	What if operation completes halfway?	Payment succeeds but order creation fails

story-map.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
USER STORY MAP: E-Commerce Shopping Experience
 
BACKBONE (User Journey Stages):
┌──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
│ DISCOVER │ EVALUATE │  BUILD   │ CHECKOUT │ RECEIVE  │  RETURN  │
│          │          │   CART   │          │          │          │
└──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘
     │          │          │          │          │          │
     ▼          ▼          ▼          ▼          ▼          ▼
WALKING SKELETON (MVP - Must Have):
┌─────────┐┌─────────┐┌─────────┐┌─────────┐┌─────────┐┌─────────┐
│ Browse  ││ View    ││ Add to  ││ Enter   ││ Track   ││ Request │
│ catalog ││ product ││ cart    ││ payment ││ order   ││ return  │
│         ││ details ││         ││         ││ status  ││         │
└─────────┘└─────────┘└─────────┘└─────────┘└─────────┘└─────────┘
     │          │          │          │          │          │
RELEASE 1 (Essential):
┌─────────┐┌─────────┐┌─────────┐┌─────────┐┌─────────┐┌─────────┐
│ Search  ││ See     ││ Update  ││ Use     ││ Email   ││ Return  │
│ by name ││ reviews ││ quantity││ saved   ││ updates ││ label   │
│         ││         ││         ││ address ││         ││ gen     │
└─────────┘└─────────┘└─────────┘└─────────┘└─────────┘└─────────┘
│ Filter  ││ Zoom    ││ Remove  ││ Choose  ││ SMS     ││ Track   │
│ results ││ images  ││ item    ││ shipping││ updates ││ refund  │
└─────────┘└─────────┘└─────────┘└─────────┘└─────────┘└─────────┘
     │          │          │          │          │          │
RELEASE 2 (Enhancement):
┌─────────┐┌─────────┐┌─────────┐┌─────────┐┌─────────┐┌─────────┐
│ Browse  ││ Compare ││ Save for││ Apply   ││ Live    ││ Exchange│
│ by cat  ││ products││ later   ││ promo   ││ tracking││ item    │
│         ││         ││         ││ code    ││         ││         │
└─────────┘└─────────┘└─────────┘└─────────┘└─────────┘└─────────┘
│ See     ││ Q&A     ││ Share   ││ Gift    ││ Predict ││ Store   │
│ trending││ section ││ cart    ││ wrap    ││ delivery││ credit  │
└─────────┘└─────────┘└─────────┘└─────────┘└─────────┘└─────────┘
 
GAP ANALYSIS:
⚠️ Missing in "EVALUATE": Availability check story
⚠️ Missing in "CHECKOUT": Guest checkout story
⚠️ Missing in "RECEIVE": Redelivery scheduling story
⚠️ Missing in "RETURN": Reason collection story
 
Story map reveals gaps that sequential story lists hide.

Coverage Is Never Complete

No matter how systematic, you will discover requirements during development. The goal isn't perfect upfront coverage—it's maximizing known coverage while remaining flexible enough to handle discoveries. Plan for iteration.

Anti-Patterns and Common Mistakes

Even experienced teams fall into predictable traps when writing user stories and use cases. Recognizing these patterns helps you avoid them.

User Story Anti-Patterns

•The Vague Story — 'As a user, I want a better experience.' No testable criteria, no clear deliverable. Stories must be specific enough to verify.
•The Technical Task — 'As a developer, I want to refactor the database.' This is a task, not a story. Stories deliver user value, not developer convenience.
•The Compound Story — 'As a user, I want to search, filter, sort, and export results.' This is 4 stories pretending to be one. Split it.
•The UI Specification — 'As a user, I want a red button that says Submit.' Stories describe outcomes, not implementations. Leave room for design.
•The Missing Why — 'As a customer, I want to see my order history.' Why? To reorder? To track spending? To dispute charges? The 'so that' reveals the true need.
•The Premature Prescription — 'As a user, I want REST APIs for all data.' This is architecture, not requirements. Focus on what users need to accomplish.
•The Orphan Story — A story with no connection to business value or user journey. If it can't be traced to value, question its necessity.

Use Case Anti-Patterns

•Functional Decomposition — Treating CRUD operations as separate use cases. 'Create Order,' 'View Order,' 'Update Order' should often be parts of larger use cases.
•The Never-Ending Use Case — A single use case covering an entire domain. If it exceeds 5 pages, it's too big. Find natural boundaries.
•Missing Actors — Forgetting external systems as actors. 'System validates payment' hides that a payment gateway is involved.
•Include/Extend Abuse — Overcomplicating with relationships. If your diagram has more arrows than ovals, simplify.
•Missing Exceptions — Documenting only the happy path. The exceptions ARE the requirements for real-world robustness.
•Implementation Details — 'System queries the PostgreSQL database.' Use cases should be implementation-independent.
•The Wishful Use Case — Describing idealized behavior that ignores real-world constraints. Include what happens when things go wrong.

anti-pattern-fixes.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
# Anti-Pattern Corrections
 
## Vague Story → Specific Story
 
❌ As a user, I want a better checkout experience.
 
✓ As a returning customer, I want to check out using my saved payment method,
  so that I can complete purchases in under 30 seconds without re-entering data.
 
 
## Technical Task → User Story
 
❌ As a developer, I want to migrate to PostgreSQL.
 
✓ As a reporting analyst, I want complex queries to complete within 5 seconds,
  so that I can generate real-time business insights.
  [Technical note: May require DB migration—team to assess]
 
 
## Compound Story → Split Stories
 
❌ As a customer, I want to search, filter, sort, and export results.
 
✓ Story 1: As a customer, I want to search products by name,
  so that I can find items I already know.
  
✓ Story 2: As a customer, I want to filter search results by price range,
  so that I only see items within my budget.
  
✓ Story 3: As a customer, I want to sort results by relevance or price,
  so that I can prioritize my browsing.
  
✓ Story 4: As a procurement manager, I want to export search results to CSV,
  so that I can analyze options in a spreadsheet.
 
 
## Missing Why → Complete Story
 
❌ As a customer, I want to see my order history.
 
✓ As a customer, I want to view my past orders,
  so that I can easily reorder items I've purchased before.
  [Note: This implies quick reorder functionality may be needed]
 
✓ As a customer, I want to view my order history sorted by date,
  so that I can track my spending over time.
  [Note: Different use case—may need spending summary feature]
 
✓ As a customer disputing a charge, I want to access order details,
  so that I can provide evidence to my bank.
  [Note: Implies need for printable/downloadable receipts]

Review Rituals Catch Anti-Patterns

Establish story/use case review as a team ritual. Fresh eyes catch anti-patterns the author is blind to. A 15-minute review before sprint planning saves hours of rework during development.

Summary: Mastering User Stories and Use Cases

User stories and use cases are the essential tools for capturing functional requirements. Mastering both—and knowing when to apply each—ensures that systems are built to match what users actually need.

Key Takeaways

•User stories capture intent — Brief narratives focusing on who, what, and why; designed for conversation, not comprehensive specification
•INVEST criteria ensure quality — Independent, Negotiable, Valuable, Estimable, Small, Testable stories are effective stories
•Acceptance criteria define done — Checklist or Gherkin format transforms subjective quality into objective verification
•Use cases provide complete specifications — When formal documentation, complex workflows, or regulatory needs exist, use cases deliver comprehensive behavioral specifications
•Diagrams show scope; documents show detail — Use case diagrams provide overview; textual use cases provide specification
•Context determines tool selection — Agile teams favor stories; regulated industries favor use cases; most mature teams use both
•Coverage requires systematic techniques — Story mapping, CRUD analysis, state machines, and exception checklists reveal gaps
•Recognize and correct anti-patterns — Vague stories, missing exceptions, and implementation details undermine requirements quality

What's Next:

With features captured through user stories and use cases, we face a new challenge: which features matter most? The next page explores feature prioritization—the frameworks and techniques Principal Engineers use to sequence work for maximum impact, from MoSCoW to RICE to opportunity scoring.

Page Complete

You now possess a comprehensive understanding of user stories and use cases—the two primary techniques for capturing functional requirements. Whether you're working in fast-paced Agile environments or regulated industries requiring formal documentation, you can select and apply the appropriate technique with expertise.