User Stories with Acceptance Criteria | Clear Scope
Write user stories that communicate value with precise acceptance criteria. GitScrum templates help developers understand and testers verify requirements.
10 min read
User stories should communicate what users need and why, enabling development teams to implement solutions while testers verify the right thing was built. Poorly written stories create confusion, rework, and delivered features that miss the mark. Clear stories with precise acceptance criteria eliminate ambiguity and accelerate delivery.
User Story Fundamentals
The Standard Format
USER STORY STRUCTURE:
┌─────────────────────────────────────────────────────────────┐
│ ANATOMY OF A GOOD USER STORY │
├─────────────────────────────────────────────────────────────┤
│ │
│ CLASSIC FORMAT: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ As a [type of user] ││
│ │ I want [some capability] ││
│ │ So that [business value/benefit] ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ WHY EACH PART MATTERS: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ "As a [user]": ││
│ │ • Clarifies perspective (admin ≠ customer) ││
│ │ • Enables empathy during implementation ││
│ │ • Helps identify edge cases for different users ││
│ │ ││
│ │ "I want [capability]": ││
│ │ • Describes need, not solution ││
│ │ • Allows creative implementation ││
│ │ • Focuses on outcome, not mechanism ││
│ │ ││
│ │ "So that [benefit]": ││
│ │ • Explains WHY (often forgotten) ││
│ │ • Enables better solutions ││
│ │ • Helps prioritization discussions ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ GOOD vs BAD EXAMPLES: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ❌ Bad: "Add export button to reports page" ││
│ │ (Specifies solution, no user, no why) ││
│ │ ││
│ │ ✅ Good: "As a marketing manager, I want to export ││
│ │ campaign reports to CSV so that I can analyze ││
│ │ performance in our BI tool without manual copying" ││
│ │ ││
│ │ ❌ Bad: "User login improvements" ││
│ │ (Vague, no specific need or benefit) ││
│ │ ││
│ │ ✅ Good: "As a returning customer, I want to stay ││
│ │ logged in for 30 days so that I don't have to ││
│ │ re-enter credentials every session" ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
Writing Acceptance Criteria
Defining "Done" Precisely
ACCEPTANCE CRITERIA PATTERNS:
┌─────────────────────────────────────────────────────────────┐
│ GIVEN-WHEN-THEN FORMAT │
├─────────────────────────────────────────────────────────────┤
│ │
│ STRUCTURE: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Given [precondition/context] ││
│ │ When [action/trigger] ││
│ │ Then [expected outcome] ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ EXAMPLE FOR EXPORT STORY: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Criterion 1: Basic export ││
│ │ Given I am viewing a campaign report ││
│ │ When I click "Export to CSV" ││
│ │ Then a CSV file downloads with all visible data ││
│ │ ││
│ │ Criterion 2: Date range handling ││
│ │ Given I have filtered the report by date range ││
│ │ When I export to CSV ││
│ │ Then only the filtered data is included ││
│ │ ││
│ │ Criterion 3: Large data handling ││
│ │ Given the report has more than 10,000 rows ││
│ │ When I export to CSV ││
│ │ Then I receive email link instead of direct download ││
│ │ ││
│ │ Criterion 4: Permission check ││
│ │ Given I do not have "export" permission ││
│ │ When I view the report ││
│ │ Then the export button is not visible ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
Alternative Criteria Formats
OTHER FORMATS:
┌─────────────────────────────────────────────────────────────┐
│ CHECKLIST FORMAT │
├─────────────────────────────────────────────────────────────┤
│ │
│ Works well for straightforward features: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ☐ Export button appears on all report pages ││
│ │ ☐ CSV includes all visible columns ││
│ │ ☐ Filename includes report name and date ││
│ │ ☐ Works in Chrome, Firefox, Safari ││
│ │ ☐ Exports complete within 10 seconds for < 1000 rows ││
│ │ ☐ Error message shown if export fails ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ RULE FORMAT: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Works well for business rules: ││
│ │ ││
│ │ Rule: Free shipping threshold ││
│ │ • Orders ≥ $50 qualify for free shipping ││
│ │ • Orders < $50 show shipping cost before checkout ││
│ │ • Threshold is configurable by admin ││
│ │ • Promotional free shipping overrides threshold ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
GitScrum Task Templates
Standardizing Story Structure
TASK TEMPLATE SETUP:
┌─────────────────────────────────────────────────────────────┐
│ CREATING REUSABLE STORY TEMPLATES │
├─────────────────────────────────────────────────────────────┤
│ │
│ USER STORY TEMPLATE: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Title: [Feature] - [Brief description] ││
│ │ ││
│ │ Description: ││
│ │ ## User Story ││
│ │ As a [user type] ││
│ │ I want [capability] ││
│ │ So that [benefit] ││
│ │ ││
│ │ ## Background ││
│ │ [Any context that helps understanding] ││
│ │ ││
│ │ ## Acceptance Criteria ││
│ │ ### Criterion 1: [Name] ││
│ │ Given [context] ││
│ │ When [action] ││
│ │ Then [result] ││
│ │ ││
│ │ ### Criterion 2: [Name] ││
│ │ Given [context] ││
│ │ When [action] ││
│ │ Then [result] ││
│ │ ││
│ │ ## Out of Scope ││
│ │ [Explicitly what this story does NOT include] ││
│ │ ││
│ │ ## Design References ││
│ │ [Links to mockups, wireframes] ││
│ │ ││
│ │ ## Technical Notes ││
│ │ [Any implementation hints or constraints] ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ CHECKLIST ITEMS: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Definition of Done: ││
│ │ ☐ All acceptance criteria met ││
│ │ ☐ Code reviewed and approved ││
│ │ ☐ Unit tests written and passing ││
│ │ ☐ Integration tests updated if needed ││
│ │ ☐ Documentation updated ││
│ │ ☐ QA sign-off received ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
Story Sizing
Making Stories Workable
STORY SPLITTING:
┌─────────────────────────────────────────────────────────────┐
│ RIGHT-SIZING USER STORIES │
├─────────────────────────────────────────────────────────────┤
│ │
│ SIZE GUIDELINES: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Too big (Epic): ││
│ │ • Takes more than one sprint ││
│ │ • Has multiple distinct user outcomes ││
│ │ • Contains "and" in the I want clause ││
│ │ ││
│ │ Right size (Story): ││
│ │ • Completable in 1-3 days ││
│ │ • Single user outcome ││
│ │ • Testable independently ││
│ │ ││
│ │ Too small (Task): ││
│ │ • No user value on its own ││
│ │ • Pure implementation detail ││
│ │ • "Create database table" ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ SPLITTING TECHNIQUES: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ By workflow step: ││
│ │ Epic: "User can manage profile" ││
│ │ → Story 1: View profile ││
│ │ → Story 2: Edit basic info ││
│ │ → Story 3: Change password ││
│ │ → Story 4: Upload avatar ││
│ │ ││
│ │ By operation (CRUD): ││
│ │ Epic: "Admin manages users" ││
│ │ → Story 1: Create user ││
│ │ → Story 2: View user list ││
│ │ → Story 3: Edit user ││
│ │ → Story 4: Deactivate user ││
│ │ ││
│ │ By business rule variation: ││
│ │ Epic: "Apply discount codes" ││
│ │ → Story 1: Percentage discount ││
│ │ → Story 2: Fixed amount discount ││
│ │ → Story 3: Free shipping discount ││
│ │ → Story 4: Stacking rules ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
Common Mistakes
What to Avoid
ANTIPATTERNS:
┌─────────────────────────────────────────────────────────────┐
│ USER STORY MISTAKES │
├─────────────────────────────────────────────────────────────┤
│ │
│ WRITING SOLUTIONS, NOT NEEDS: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ❌ "As a user, I want a dropdown menu with sorting ││
│ │ options so that I can sort the table" ││
│ │ ││
│ │ ✅ "As a user, I want to sort products by price so ││
│ │ that I can find items within my budget quickly" ││
│ │ ││
│ │ Why: First specifies implementation, second allows ││
│ │ team to find best solution ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ MISSING ACCEPTANCE CRITERIA: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Story without criteria: ││
│ │ "As a user, I want to search products" ││
│ │ → How do we know when it's done? ││
│ │ → What constitutes a valid search? ││
│ │ → What happens with no results? ││
│ │ ││
│ │ Same story with criteria: ││
│ │ Given: Products exist in catalog ││
│ │ When: User enters search term and submits ││
│ │ Then: Matching products display within 2 seconds ││
│ │ ││
│ │ Given: No products match search ││
│ │ When: User submits search ││
│ │ Then: "No results" message with suggestions appears ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ VAGUE CRITERIA: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ❌ "Page should load quickly" ││
│ │ ✅ "Page loads in under 3 seconds on 3G connection" ││
│ │ ││
│ │ ❌ "Export should handle large files" ││
│ │ ✅ "Export handles up to 100,000 rows without timeout" ││
│ │ ││
│ │ ❌ "Form validates input" ││
│ │ ✅ "Email field rejects invalid format with error ││
│ │ message 'Please enter a valid email address'" ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
Quality Checklist
Story Readiness
INVEST CRITERIA:
┌─────────────────────────────────────────────────────────────┐
│ EVALUATING STORY QUALITY │
├─────────────────────────────────────────────────────────────┤
│ │
│ I - INDEPENDENT: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ☐ Can be developed without other stories ││
│ │ ☐ No circular dependencies ││
│ │ ☐ Can be prioritized freely ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ N - NEGOTIABLE: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ☐ Details can be discussed ││
│ │ ☐ Not a contract, a conversation ││
│ │ ☐ Implementation flexible ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ V - VALUABLE: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ☐ Delivers value to user or business ││
│ │ ☐ "So that" explains clear benefit ││
│ │ ☐ Stakeholder understands value ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ E - ESTIMABLE: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ☐ Team can estimate effort ││
│ │ ☐ Scope is understood ││
│ │ ☐ Technical approach is clear enough ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ S - SMALL: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ☐ Completable in days, not weeks ││
│ │ ☐ Single sprint maximum ││
│ │ ☐ Can be split if too large ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ T - TESTABLE: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ☐ Acceptance criteria are verifiable ││
│ │ ☐ QA can write test cases from criteria ││
│ │ ☐ Success/failure is objective, not subjective ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘