User Story Writing | Format, INVEST, and Examples
Write user stories that communicate value and enable estimation. Learn the standard format, INVEST criteria, and acceptance criteria with GitScrum.
7 min read
User stories capture what users need in a format teams can act on. Good stories communicate value clearly and enable good planning. Poor stories create confusion and missed expectations. This guide covers practical story writing techniques.
Story Structure
| Component | Purpose | Required |
|---|---|---|
| User role | Who benefits | Yes |
| Goal | What they want | Yes |
| Benefit | Why it matters | Yes |
| Acceptance criteria | How to verify | Yes |
Story Format
Standard Template
USER STORY FORMAT
═════════════════
THE TEMPLATE:
─────────────────────────────────────
As a [type of user]
I want [goal/capability]
So that [benefit/value]
Acceptance Criteria:
├── Given [context]
├── When [action]
├── Then [expected result]
└── (multiple criteria)
GOOD EXAMPLE:
─────────────────────────────────────
As a logged-in customer
I want to save my shopping cart
So that I can return later to complete my purchase
Acceptance Criteria:
├── Given I have items in my cart
│ When I navigate away and return
│ Then my cart items are preserved
├── Given I am logged out
│ When I log back in
│ Then my cart is restored
├── Given my cart has been saved for 30 days
│ When I log in
│ Then I see a message that expired items were removed
BAD EXAMPLE:
─────────────────────────────────────
"Implement cart persistence"
├── No user perspective
├── No value statement
├── No acceptance criteria
├── Just a task
└── Not a story
INVEST Criteria
Quality Checklist
INVEST CRITERIA
═══════════════
I - INDEPENDENT:
─────────────────────────────────────
├── Can be done without other stories
├── Order can be changed
├── Team can pick any from sprint
└── No blocking dependencies
N - NEGOTIABLE:
─────────────────────────────────────
├── Details can be discussed
├── Not a contract
├── Conversation starter
├── Implementation flexible
└── Collaborate on solution
V - VALUABLE:
─────────────────────────────────────
├── Delivers value to user/business
├── Clear benefit
├── Worth doing
├── Not just technical task
└── User-centric
E - ESTIMABLE:
─────────────────────────────────────
├── Team can size it
├── Understood enough
├── If can't estimate, needs refinement
├── Questions answered
└── Clarity for planning
S - SMALL:
─────────────────────────────────────
├── Fits in one sprint
├── Ideally 1-3 days work
├── Large stories = split
├── Completable
└── Manageable scope
T - TESTABLE:
─────────────────────────────────────
├── Clear acceptance criteria
├── Can verify when done
├── Objective completion
├── Not subjective
└── Know when finished
INVESTMENT CHECK:
─────────────────────────────────────
For each story ask:
├── Can it stand alone? (I)
├── Can we discuss details? (N)
├── Does it deliver value? (V)
├── Can we estimate it? (E)
├── Does it fit in a sprint? (S)
├── Can we test completion? (T)
└── All yes = ready for sprint
Acceptance Criteria
Defining Done
ACCEPTANCE CRITERIA
═══════════════════
GHERKIN FORMAT:
─────────────────────────────────────
Given [precondition/context]
When [action/trigger]
Then [expected outcome]
EXAMPLE:
─────────────────────────────────────
Story: User login
AC1: Successful login
├── Given I am on the login page
├── When I enter valid email and password
├── Then I am redirected to the dashboard
└── And I see my name in the header
AC2: Invalid credentials
├── Given I am on the login page
├── When I enter invalid password
├── Then I see "Invalid credentials" error
└── And I remain on the login page
AC3: Account locked
├── Given I have failed login 5 times
├── When I try to login again
├── Then I see "Account locked" message
└── And I receive email with unlock link
GOOD CRITERIA:
─────────────────────────────────────
├── Specific and testable
├── Cover main scenarios
├── Include edge cases
├── Clear expected behavior
├── No ambiguity
└── Team can verify
BAD CRITERIA:
─────────────────────────────────────
├── "Works correctly"
├── "Looks good"
├── "Fast performance"
├── "Easy to use"
├── Vague and untestable
└── No clear verification
Story Splitting
Breaking Down Large Stories
STORY SPLITTING TECHNIQUES
══════════════════════════
BY WORKFLOW STEPS:
─────────────────────────────────────
Large: "User can checkout"
Split:
├── User can view cart
├── User can enter shipping address
├── User can enter payment details
├── User can review and confirm order
├── User receives confirmation
└── Each step is valuable
BY USER TYPE:
─────────────────────────────────────
Large: "Users can manage subscriptions"
Split:
├── Free users can view plans
├── Premium users can change plan
├── Admin can manage all subscriptions
└── Different user, different story
BY DATA VARIATIONS:
─────────────────────────────────────
Large: "Support multiple payment methods"
Split:
├── User can pay with credit card
├── User can pay with PayPal
├── User can pay with bank transfer
└── One method at a time
BY OPERATIONS:
─────────────────────────────────────
Large: "User can manage profile"
Split:
├── User can view profile
├── User can edit profile
├── User can upload avatar
├── User can delete account
└── CRUD operations
BY HAPPY PATH VS EDGE CASES:
─────────────────────────────────────
Large: "Robust file upload"
Split:
├── User can upload valid image (happy path)
├── System validates file type
├── System handles large files
├── System handles upload failure
└── Start with happy path
SPLITTING RULES:
─────────────────────────────────────
Good splits:
├── Each slice delivers value
├── Each is testable
├── Each fits in sprint
├── User would recognize it
└── Valuable increment
Bad splits:
├── "Design the UI"
├── "Build the API"
├── "Write tests"
├── Technical layers
└── Not user value
Story Refinement
Preparing Stories
STORY REFINEMENT
════════════════
REFINEMENT SESSION:
─────────────────────────────────────
Purpose:
├── Clarify stories
├── Add acceptance criteria
├── Estimate
├── Split if needed
├── Identify dependencies
└── Sprint-ready
DISCUSSION POINTS:
─────────────────────────────────────
For each story:
├── What does this mean?
├── Who is the user?
├── What is the value?
├── What are the acceptance criteria?
├── Any edge cases?
├── Dependencies?
├── Estimate?
└── Shared understanding
READY FOR SPRINT:
─────────────────────────────────────
Story is ready when:
├── ☐ Clear user and value
├── ☐ Acceptance criteria defined
├── ☐ Estimated by team
├── ☐ Small enough for sprint
├── ☐ Dependencies identified
├── ☐ Team understands it
└── Definition of ready
GitScrum Stories
Tool Usage
GITSCRUM FOR STORIES
════════════════════
STORY CREATION:
─────────────────────────────────────
├── Use user story template
├── Fill in user, want, so that
├── Add acceptance criteria
├── Add estimate
├── Assign to sprint
└── Structured format
ACCEPTANCE CRITERIA:
─────────────────────────────────────
├── Checklist format
├── Given/When/Then in description
├── Check off during development
├── Verify before closing
└── Clear completion
LABELS:
─────────────────────────────────────
├── user-story
├── needs-refinement
├── ready
├── Category labels
└── Clear status
BACKLOG:
─────────────────────────────────────
├── Prioritized backlog
├── Refined stories at top
├── Rough stories below
├── Continuous refinement
└── Always have sprint-ready stories
Best Practices
For User Stories
Anti-Patterns
USER STORY MISTAKES:
✗ Technical tasks as stories
✗ Missing acceptance criteria
✗ Stories too large
✗ No value statement
✗ Vague language
✗ Solution in story (should be problem)
✗ Skip refinement
✗ Treat as contract