User Story Writing Best Practices | INVEST Criteria
Write effective user stories with INVEST criteria and acceptance conditions. GitScrum supports story points, sprint planning, and user-focused development.
11 min read
User stories are the fundamental unit of work in agile development—they describe what users need in a way that developers can understand and deliver. Well-written stories are Independent, Negotiable, Valuable, Estimable, Small, and Testable (INVEST). GitScrum's task management features support story-driven development with acceptance criteria, story points, and sprint planning that keeps work focused on user value.
User Story Components
| Component | Purpose | Required |
|---|---|---|
| Title | Quick reference | Yes |
| User role | Who benefits | Yes |
| Action | What they want | Yes |
| Benefit | Why it matters | Yes |
| Acceptance Criteria | Definition of done | Yes |
| Notes | Context, details | Optional |
Story Format
USER STORY STRUCTURE
STANDARD FORMAT:
┌─────────────────────────────────────────────────┐
│ As a [user role] │
│ I want [action/feature] │
│ So that [benefit/value] │
│ │
│ Example: │
│ As a project manager │
│ I want to export sprint reports to PDF │
│ So that I can share progress with stakeholders │
│ who don't have system access │
└─────────────────────────────────────────────────┘
USER ROLES:
┌─────────────────────────────────────────────────┐
│ Be specific about who: │
│ │
│ ✗ As a user... │
│ ✓ As a project manager... │
│ ✓ As a first-time visitor... │
│ ✓ As an enterprise admin... │
│ ✓ As a developer on the team... │
│ │
│ Different roles = different needs │
└─────────────────────────────────────────────────┘
THE "SO THAT" CLAUSE:
┌─────────────────────────────────────────────────┐
│ Most important part - explains value │
│ │
│ ✗ "So that I can export reports" │
│ (just repeats the action) │
│ │
│ ✓ "So that I can share progress with │
│ stakeholders who don't have access" │
│ (explains the real benefit) │
│ │
│ If you can't explain why, question if needed │
└─────────────────────────────────────────────────┘
INVEST Criteria
INVEST CHECKLIST
INDEPENDENT:
┌─────────────────────────────────────────────────┐
│ ✓ Can be developed in any order │
│ ✓ No dependency on other stories │
│ ✓ Can be released independently │
│ │
│ ✗ "Complete payment after checkout story" │
│ ✓ "Process payment for cart" │
│ (includes what's needed to work alone) │
└─────────────────────────────────────────────────┘
NEGOTIABLE:
┌─────────────────────────────────────────────────┐
│ ✓ Details can be discussed │
│ ✓ Not a fixed specification │
│ ✓ Room for technical input │
│ │
│ ✗ "Build exactly this wireframe" │
│ ✓ "Users need to reset password easily" │
│ (team can propose solution) │
└─────────────────────────────────────────────────┘
VALUABLE:
┌─────────────────────────────────────────────────┐
│ ✓ Delivers value to user or business │
│ ✓ Stakeholder would pay for it │
│ ✓ Can explain why it matters │
│ │
│ ✗ "Refactor auth module" │
│ (technical, no user value stated) │
│ ✓ "Users can login in under 3 seconds" │
│ (value is clear) │
└─────────────────────────────────────────────────┘
ESTIMABLE:
┌─────────────────────────────────────────────────┐
│ ✓ Team can estimate the effort │
│ ✓ Enough detail to size │
│ ✓ Not too vague │
│ │
│ ✗ "Improve the dashboard" │
│ (too vague to estimate) │
│ ✓ "Add export button to dashboard that │
│ generates CSV of visible data" │
└─────────────────────────────────────────────────┘
SMALL:
┌─────────────────────────────────────────────────┐
│ ✓ Fits in a sprint │
│ ✓ Ideally 1-5 days of work │
│ ✓ Can be completed by 1-2 people │
│ │
│ ✗ "Build the entire reporting module" │
│ (epic, not a story) │
│ ✓ "Generate revenue summary report" │
│ (one focused piece) │
└─────────────────────────────────────────────────┘
TESTABLE:
┌─────────────────────────────────────────────────┐
│ ✓ Clear pass/fail criteria │
│ ✓ Can verify it works │
│ ✓ No subjective measures │
│ │
│ ✗ "Make the dashboard beautiful" │
│ (subjective) │
│ ✓ "Dashboard loads in under 2 seconds" │
│ (measurable) │
└─────────────────────────────────────────────────┘
Acceptance Criteria
WRITING ACCEPTANCE CRITERIA
GIVEN-WHEN-THEN FORMAT:
┌─────────────────────────────────────────────────┐
│ Given [context/precondition] │
│ When [action/trigger] │
│ Then [expected outcome] │
│ │
│ Example: │
│ Given I am on the dashboard │
│ When I click "Export CSV" │
│ Then a CSV file downloads with visible data │
│ │
│ Given I have no data for the date range │
│ When I click "Export CSV" │
│ Then I see "No data to export" message │
└─────────────────────────────────────────────────┘
CHECKLIST FORMAT:
┌─────────────────────────────────────────────────┐
│ Acceptance Criteria: │
│ ☐ Export button visible on dashboard │
│ ☐ CSV includes all visible columns │
│ ☐ Filename includes current date │
│ ☐ Large exports (>10K rows) show progress │
│ ☐ Empty state shows helpful message │
│ ☐ Works in Chrome, Firefox, Safari │
└─────────────────────────────────────────────────┘
HOW MANY CRITERIA:
┌─────────────────────────────────────────────────┐
│ 3-8 criteria is typical │
│ │
│ Too few (1-2): May miss important cases │
│ Too many (10+): Story probably too big │
│ │
│ Focus on: │
│ ├── Main success path │
│ ├── Key error cases │
│ ├── Edge cases that matter │
│ └── Non-functional requirements │
└─────────────────────────────────────────────────┘
Story Types
DIFFERENT STORY TYPES
FEATURE STORY:
┌─────────────────────────────────────────────────┐
│ As a project manager │
│ I want to set task dependencies │
│ So that my team knows what to work on next │
│ │
│ Acceptance Criteria: │
│ ☐ Can link task A as dependency of task B │
│ ☐ Dependent tasks show warning if blocked │
│ ☐ Can remove dependencies │
│ ☐ Circular dependencies are prevented │
└─────────────────────────────────────────────────┘
BUG-FIX STORY:
┌─────────────────────────────────────────────────┐
│ As a user │
│ I want the login to work on Safari │
│ So that I can access my account from any │
│ browser │
│ │
│ Current behavior: Login fails silently │
│ Expected behavior: Login works like Chrome │
│ │
│ Acceptance Criteria: │
│ ☐ Login works in Safari 15+ │
│ ☐ Error messages display correctly │
│ ☐ Session persists correctly │
└─────────────────────────────────────────────────┘
TECHNICAL STORY:
┌─────────────────────────────────────────────────┐
│ As a developer │
│ I want automated tests for the payment module │
│ So that we can refactor with confidence │
│ │
│ Note: Still has value statement │
│ Note: Benefits developers as users │
│ │
│ Acceptance Criteria: │
│ ☐ 80% test coverage for payment service │
│ ☐ Tests run in under 60 seconds │
│ ☐ All edge cases documented │
└─────────────────────────────────────────────────┘
SPIKE (RESEARCH):
┌─────────────────────────────────────────────────┐
│ Spike: Evaluate GraphQL for API │
│ │
│ Questions to answer: │
│ ├── Does it meet our performance requirements? │
│ ├── What's the learning curve for team? │
│ ├── How does it integrate with auth? │
│ └── Estimated effort to migrate? │
│ │
│ Time-box: 3 days │
│ Output: Decision document │
│ │
│ Note: Spikes are time-boxed research, │
│ not deliverables │
└─────────────────────────────────────────────────┘
Splitting Stories
BREAKING DOWN LARGE STORIES
WHEN TO SPLIT:
┌─────────────────────────────────────────────────┐
│ Story is too big when: │
│ ├── Can't complete in one sprint │
│ ├── Estimate is "large" or "XL" │
│ ├── Has many acceptance criteria │
│ ├── Feels uncertain or vague │
│ └── Multiple user roles involved │
└─────────────────────────────────────────────────┘
SPLITTING PATTERNS:
┌─────────────────────────────────────────────────┐
│ By workflow steps: │
│ ├── Story 1: User can upload file │
│ ├── Story 2: User can preview file │
│ └── Story 3: User can download processed file │
│ │
│ By user role: │
│ ├── Story 1: Admin can manage users │
│ └── Story 2: User can update their profile │
│ │
│ By data variation: │
│ ├── Story 1: Export to CSV │
│ └── Story 2: Export to PDF │
│ │
│ By complexity: │
│ ├── Story 1: Basic search (text match) │
│ └── Story 2: Advanced search (filters, sort) │
│ │
│ By happy path vs edge cases: │
│ ├── Story 1: Login with valid credentials │
│ └── Story 2: Handle login failures gracefully │
└─────────────────────────────────────────────────┘
SPLIT EXAMPLE:
┌─────────────────────────────────────────────────┐
│ Original (too big): │
│ "User can manage their profile" │
│ │
│ Split into: │
│ ├── User can view their profile │
│ ├── User can update name and email │
│ ├── User can change password │
│ ├── User can upload profile picture │
│ └── User can delete their account │
│ │
│ Each is now independent and small │
└─────────────────────────────────────────────────┘
Common Mistakes
USER STORY ANTI-PATTERNS
TECHNICAL IMPLEMENTATION:
┌─────────────────────────────────────────────────┐
│ ✗ "Create REST endpoint for user data" │
│ ✗ "Add React component for form" │
│ ✗ "Implement caching layer" │
│ │
│ These are tasks, not stories │
│ Stories describe user value │
│ │
│ ✓ "User can update their profile quickly" │
│ (caching is implementation detail) │
└─────────────────────────────────────────────────┘
SOLUTION IN STORY:
┌─────────────────────────────────────────────────┐
│ ✗ "As a user, I want a dropdown menu with │
│ exactly these options: A, B, C" │
│ │
│ Prescribes solution instead of problem │
│ │
│ ✓ "As a user, I want to filter projects by │
│ status so I can focus on active work" │
│ (team decides dropdown vs tabs vs filters) │
└─────────────────────────────────────────────────┘
MISSING VALUE:
┌─────────────────────────────────────────────────┐
│ ✗ "As a user, I want dark mode" │
│ (no "so that" - why does it matter?) │
│ │
│ ✓ "As a user working at night, I want dark │
│ mode so that I can use the app without │
│ eye strain" │
└─────────────────────────────────────────────────┘
TOO VAGUE:
┌─────────────────────────────────────────────────┐
│ ✗ "As a user, I want the app to be fast" │
│ (not estimable or testable) │
│ │
│ ✓ "As a user, I want the dashboard to load │
│ in under 2 seconds so I can start work │
│ immediately" │
└─────────────────────────────────────────────────┘
TOO BIG (EPIC):
┌─────────────────────────────────────────────────┐
│ ✗ "As a user, I want a complete reporting │
│ system" │
│ (months of work) │
│ │
│ Break into: │
│ ├── View basic report │
│ ├── Filter report by date │
│ ├── Export report to CSV │
│ └── Schedule automated reports │
└─────────────────────────────────────────────────┘
Refinement Process
STORY REFINEMENT
BEFORE REFINEMENT:
┌─────────────────────────────────────────────────┐
│ PO prepares: │
│ ├── Draft user story │
│ ├── Initial acceptance criteria │
│ ├── Context and background │
│ └── Questions that need team input │
└─────────────────────────────────────────────────┘
DURING REFINEMENT:
┌─────────────────────────────────────────────────┐
│ Team discusses: │
│ ├── Clarifying questions │
│ ├── Edge cases and error handling │
│ ├── Technical considerations │
│ ├── Splitting if too big │
│ └── Initial estimation │
│ │
│ Outcome: │
│ ├── Story is clear and understood │
│ ├── Acceptance criteria finalized │
│ ├── Story is estimated │
│ └── Ready for sprint planning │
└─────────────────────────────────────────────────┘
DEFINITION OF READY:
┌─────────────────────────────────────────────────┐
│ Story is ready for sprint when: │
│ ☐ User value is clear │
│ ☐ Acceptance criteria defined │
│ ☐ Team understands scope │
│ ☐ Story is estimated │
│ ☐ Dependencies identified │
│ ☐ Small enough for sprint │
└─────────────────────────────────────────────────┘
Best Practices
Anti-Patterns
✗ Technical tasks as stories
✗ No user value stated
✗ Solution baked into story
✗ Too big to estimate
✗ Vague acceptance criteria
✗ Skipping refinement