Writing Effective User Stories | INVEST Criteria Guide
Master user stories with INVEST criteria and Given-When-Then acceptance criteria. Learn story splitting techniques. GitScrum tracks stories in sprints.
9 min read
User stories are not requirements documents—they're placeholders for conversations. A good user story captures who needs what and why, is small enough to complete in a sprint, and invites discussion about the details. This guide covers writing stories that actually help teams build the right thing.
Story Elements
| Element | Purpose | Example |
|---|---|---|
| User Role | Who benefits | "As a customer..." |
| Goal | What they want | "...I want to save my cart..." |
| Benefit | Why it matters | "...so I can return later" |
| Criteria | Definition of done | "Cart persists for 30 days" |
Story Format
The Classic Template
USER STORY TEMPLATE
═══════════════════
FORMAT:
─────────────────────────────────────
As a [user type]
I want [goal/desire]
So that [benefit/value]
Acceptance Criteria:
├── Given [context], when [action], then [outcome]
├── Given [context], when [action], then [outcome]
└── ...
EXAMPLE:
─────────────────────────────────────
As a frequent shopper
I want to save items to my wishlist
So that I can easily find them later for purchase
Acceptance Criteria:
├── Given I'm on a product page
│ When I click "Add to Wishlist"
│ Then the item appears in my wishlist
│
├── Given I'm viewing my wishlist
│ When I click "Add to Cart" on an item
│ Then the item moves to my cart
│
├── Given I have items in my wishlist
│ When I return next week
│ Then my wishlist items are still there
│
└── Given an item becomes unavailable
When I view my wishlist
Then I see "Out of stock" on that item
COMPONENTS EXPLAINED:
─────────────────────────────────────
USER TYPE:
├── Who is this for?
├── Be specific: "New user" vs "Admin" vs "Premium subscriber"
├── Persona if you have them
└── Helps prioritize and design
GOAL:
├── What do they want to do?
├── Functional capability
├── Not HOW, just WHAT
└── User language, not technical
BENEFIT:
├── Why does this matter?
├── The real motivation
├── Helps understand trade-offs
└── Sometimes reveals better solutions
INVEST Criteria
Story Quality Check
INVEST CRITERIA
═══════════════
I - INDEPENDENT
─────────────────────────────────────
Stories should be completable on their own.
Not: "User can pay (requires cart story)"
Yes: Each story deliverable independently
If dependencies exist, note them but minimize.
N - NEGOTIABLE
─────────────────────────────────────
Stories are conversation starters, not contracts.
Details emerge through discussion.
Don't over-specify upfront.
Room for team input on implementation.
V - VALUABLE
─────────────────────────────────────
Each story delivers value to someone.
Not: "Install database" (no user value directly)
Yes: "User can save preferences" (value)
Technical work can be stories, but link to value.
E - ESTIMABLE
─────────────────────────────────────
Team can estimate the effort.
If not estimable:
├── Too vague → Need more detail
├── Too big → Need to split
├── Too new → Need spike/research
└── Team must understand scope
S - SMALL
─────────────────────────────────────
Completable in a sprint, ideally 1-5 days.
If larger: Split into multiple stories.
Smaller stories = faster feedback.
T - TESTABLE
─────────────────────────────────────
Clear acceptance criteria.
You can verify it works.
Not: "Fast performance" (vague)
Yes: "Page loads in under 2 seconds" (testable)
Acceptance Criteria
Writing Good Criteria
ACCEPTANCE CRITERIA
═══════════════════
PURPOSE:
─────────────────────────────────────
├── Define "done" for the story
├── Enable testing
├── Clarify requirements
├── Prevent scope creep
└── Agreement between team and PO
FORMAT (Given-When-Then):
─────────────────────────────────────
Given [precondition/context]
When [action/trigger]
Then [expected outcome]
EXAMPLE STORY:
─────────────────────────────────────
As a user
I want to reset my password
So that I can regain access to my account
Acceptance Criteria:
✓ Given I'm on the login page
When I click "Forgot Password"
Then I see a form requesting my email
✓ Given I enter a registered email
When I submit the form
Then I receive a password reset email within 5 min
✓ Given I click the reset link in email
When the link is less than 24 hours old
Then I see a form to enter new password
✓ Given I click the reset link in email
When the link is more than 24 hours old
Then I see "Link expired" with option to request new
✓ Given I enter a new valid password
When I submit
Then my password is changed and I can log in
✓ Given I enter invalid password (too short)
When I submit
Then I see validation error, password unchanged
CRITERIA GUIDELINES:
─────────────────────────────────────
├── 3-8 criteria per story typically
├── Cover happy path AND edge cases
├── Specific and measurable
├── Written before development
├── Refined in grooming
└── Team and PO agree
Splitting Stories
When and How
STORY SPLITTING TECHNIQUES
══════════════════════════
SPLIT WHEN:
─────────────────────────────────────
├── Story is > 8 points (too big)
├── Can't estimate (too vague)
├── Multiple acceptance criteria clusters
├── Different user flows
├── Takes more than one sprint
└── Team feels uncertain
SPLITTING PATTERNS:
─────────────────────────────────────
1. BY WORKFLOW STEP
Original: "User can purchase product"
Split:
├── User can add to cart
├── User can enter shipping
├── User can enter payment
└── User can confirm purchase
2. BY DATA VARIATION
Original: "User can log in"
Split:
├── User can log in with email/password
├── User can log in with Google
└── User can log in with SSO
3. BY BUSINESS RULE
Original: "User can apply discount"
Split:
├── User can apply percentage discount
├── User can apply fixed amount discount
└── User can apply free shipping discount
4. BY OPERATION (CRUD)
Original: "User can manage contacts"
Split:
├── User can create contact
├── User can view contact
├── User can edit contact
└── User can delete contact
5. BY PLATFORM
Original: "User can view dashboard"
Split:
├── User can view dashboard (web)
├── User can view dashboard (mobile)
└── User can view dashboard (tablet)
6. BY COMPLEXITY
Original: "User can search products"
Split:
├── User can search by name (simple)
├── User can filter by category
└── User can use advanced filters
BAD SPLITS:
─────────────────────────────────────
✗ Frontend / Backend (not independent)
✗ Design / Development (not independent)
✗ Happy path / Error handling (both needed)
✗ Implementation phases (not valuable alone)
Common Mistakes
What to Avoid
USER STORY MISTAKES
═══════════════════
TOO VAGUE:
─────────────────────────────────────
✗ "As a user, I want the system to be fast"
✓ "As a user, I want search results in < 1 second"
TOO TECHNICAL:
─────────────────────────────────────
✗ "As a developer, I want to refactor the auth module"
✓ "As a user, I want login to work reliably"
(refactoring is HOW, not WHAT)
NO BENEFIT:
─────────────────────────────────────
✗ "As a user, I want a blue button"
Why? What value does blue provide?
✓ "As a user, I want clear call-to-action
so I know what to do next"
SOLUTION IN STORY:
─────────────────────────────────────
✗ "As a user, I want a dropdown menu with..."
That's a solution. What's the need?
✓ "As a user, I want to select my country
so I see relevant content"
(dropdown might not be the best solution)
TOO BIG:
─────────────────────────────────────
✗ "As a user, I want to complete the checkout process"
This is an epic, not a story. Split it.
NO ACCEPTANCE CRITERIA:
─────────────────────────────────────
✗ Story with no criteria = no definition of done
Team guesses what's expected
Arguments at demo
FAKE USER:
─────────────────────────────────────
✗ "As a system, I want to send emails"
Systems don't "want" things
✓ "As a customer, I want email confirmation
so I know my order was received"
GitScrum Stories
Story Management
GITSCRUM STORY FEATURES
═══════════════════════
CREATING STORIES:
─────────────────────────────────────
Task → Type: User Story
Fields:
├── Title: "As a... I want... so that..."
├── Description: Full story text
├── Acceptance Criteria: Checklist format
├── Story Points: Estimate
├── Labels: Feature area
└── Sprint: When planned
ACCEPTANCE CRITERIA AS CHECKLIST:
─────────────────────────────────────
In description or custom field:
☐ Given logged in, when click wishlist, then see items
☐ Given item unavailable, when view wishlist, then see status
☐ Given 30 days passed, when return, then items still there
Check off as you complete.
All checked = story done.
STORY HIERARCHY:
─────────────────────────────────────
Epic: User Authentication
├── Story: Login with email/password
├── Story: Login with Google
├── Story: Password reset
├── Story: Remember me
└── Story: Logout
Each story independent and valuable.
REFINEMENT WORKFLOW:
─────────────────────────────────────
Status: Draft → Refined → Ready → Sprint
Draft: Initial capture
Refined: Discussed, criteria added
Ready: Estimated, team understands
Sprint: Committed to sprint
Best Practices
For User Stories
Anti-Patterns
STORY MISTAKES:
✗ Requirements documents disguised as stories
✗ Technical tasks as user stories
✗ No acceptance criteria
✗ Epic-sized stories
✗ Solution before problem
✗ No user benefit stated
✗ Written in isolation (no team input)
✗ Never refined before sprint