User Story Writing

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

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

1. Include the why — Value matters
2. Write acceptance criteria — Testable completion
3. Keep stories small — Fit in sprint
4. User perspective — Not technical tasks
5. Refine before sprint — Ready to work

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

Related Solutions

• Creating effective sprint backlogs
• Prioritizing backlog items effectively
• Agile estimation techniques