9 min read • Guide 747 of 877
Writing Better User Stories
Good user stories communicate intent clearly. GitScrum provides templates and fields that help teams write stories with the right level of detail.
User Story Basics
Story Format
USER STORY STRUCTURE:
┌─────────────────────────────────────────────────────────────┐
│ │
│ CLASSIC FORMAT: │
│ │
│ As a [type of user] │
│ I want [some goal] │
│ So that [some reason/benefit] │
│ │
│ EXAMPLE: │
│ │
│ As a project manager │
│ I want to export reports to PDF │
│ So that I can share progress with stakeholders │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ WHY THIS FORMAT WORKS: │
│ │
│ WHO: Identifies the user type │
│ → Helps understand context │
│ │
│ WHAT: States the desired functionality │
│ → Clear goal │
│ │
│ WHY: Explains the underlying need │
│ → Enables alternative solutions │
│ → Prevents "just build what I said" │
│ │
│ ALTERNATIVE FORMAT (if simpler): │
│ │
│ "Allow project managers to export PDF reports" │
│ │
│ The format is a tool, not a rule │
│ Clarity > following format rigidly │
└─────────────────────────────────────────────────────────────┘
INVEST Criteria
INVEST CHECKLIST:
┌─────────────────────────────────────────────────────────────┐
│ │
│ I - INDEPENDENT │
│ Can be developed without depending on other stories │
│ ❌ "After story A is done, we can do B" │
│ ✅ Story B stands on its own │
│ │
│ N - NEGOTIABLE │
│ Details can be discussed and adjusted │
│ ❌ "Build exactly this UI with these 27 fields" │
│ ✅ "User needs to configure notifications" │
│ │
│ V - VALUABLE │
│ Delivers value to user or business │
│ ❌ "Refactor the database layer" │
│ ✅ "Users experience faster page loads" │
│ │
│ E - ESTIMABLE │
│ Team can estimate the effort │
│ ❌ Too vague to size │
│ ✅ Clear enough to discuss complexity │
│ │
│ S - SMALL │
│ Fits within a sprint │
│ ❌ "Build the entire checkout system" │
│ ✅ "Add credit card payment option" │
│ │
│ T - TESTABLE │
│ Can verify when complete │
│ ❌ "Make the app faster" │
│ ✅ "Page loads in under 2 seconds" │
│ │
│ USE THIS: Review stories against INVEST before planning │
└─────────────────────────────────────────────────────────────┘
Acceptance Criteria
Writing Criteria
ACCEPTANCE CRITERIA EXAMPLES:
┌─────────────────────────────────────────────────────────────┐
│ │
│ STORY: As a user, I can export my data to CSV │
│ │
│ ACCEPTANCE CRITERIA: │
│ │
│ ✅ GOOD CRITERIA: │
│ │
│ GIVEN I am on the data grid page │
│ WHEN I click the "Export" button │
│ THEN a CSV file downloads to my computer │
│ │
│ GIVEN I have selected specific columns │
│ WHEN I export │
│ THEN only selected columns appear in the CSV │
│ │
│ GIVEN the dataset has 50,000 rows │
│ WHEN I export │
│ THEN the export completes within 30 seconds │
│ AND I see a progress indicator │
│ │
│ GIVEN the data contains special characters │
│ WHEN I export and open in Excel │
│ THEN the characters display correctly │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ ❌ BAD CRITERIA: │
│ │
│ "Export should work" │
│ → Too vague, what does "work" mean? │
│ │
│ "Use the CSVExporter library with UTF-8 encoding" │
│ → Too technical, prescribes implementation │
│ │
│ "Export should be fast" │
│ → Not measurable, fast for whom? │
└─────────────────────────────────────────────────────────────┘
Criteria Formats
ACCEPTANCE CRITERIA FORMATS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ FORMAT 1: GIVEN-WHEN-THEN (BDD) │
│ │
│ GIVEN [context/precondition] │
│ WHEN [action taken] │
│ THEN [expected outcome] │
│ │
│ Best for: Complex scenarios, QA automation │
│ │
│ FORMAT 2: CHECKLIST │
│ │
│ ☐ Export button visible on data grid │
│ ☐ CSV file downloads on click │
│ ☐ All columns included in export │
│ ☐ Special characters handled correctly │
│ ☐ Large datasets export without timeout │
│ │
│ Best for: Simple stories, quick validation │
│ │
│ FORMAT 3: BULLET POINTS │
│ │
│ • User can click Export button │
│ • File downloads as CSV │
│ • Includes selected columns only │
│ • Handles up to 50k rows │
│ │
│ Best for: Straightforward requirements │
│ │
│ PICK THE FORMAT THAT WORKS FOR YOUR TEAM │
│ Consistency > format correctness │
└─────────────────────────────────────────────────────────────┘
Common Mistakes
Story Anti-Patterns
USER STORY ANTI-PATTERNS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ ❌ TOO BIG: │
│ │
│ "As a user, I can manage my entire account" │
│ → Split into: View profile, Edit profile, Change password │
│ │
│ ❌ TECHNICAL TASK: │
│ │
│ "Migrate database to PostgreSQL" │
│ → That's a task, not a user story │
│ → User story: "System handles 10x more concurrent users" │
│ │
│ ❌ SOLUTION INSTEAD OF PROBLEM: │
│ │
│ "Add a dropdown with A, B, C options" │
│ → Why? What problem does this solve? │
│ → Better: "User can filter by category" │
│ │
│ ❌ NO "WHY": │
│ │
│ "As a user, I want a dark mode" │
│ → So that what? Reduced eye strain? Brand consistency? │
│ → The "why" enables better solutions │
│ │
│ ❌ VAGUE ACCEPTANCE: │
│ │
│ "It should be user-friendly" │
│ → What does that mean? How do we test it? │
│ │
│ ❌ DEVELOPER-FOCUSED: │
│ │
│ "As a developer, I want to refactor the auth module" │
│ → Users don't care about this │
│ → Rephrase as user benefit or make it a technical task │
└─────────────────────────────────────────────────────────────┘
Fixing Bad Stories
IMPROVING PROBLEMATIC STORIES:
┌─────────────────────────────────────────────────────────────┐
│ │
│ BEFORE: "Add login functionality" │
│ │
│ Problems: │
│ • No user perspective │
│ • No reason given │
│ • No acceptance criteria │
│ • Too vague to estimate │
│ │
│ AFTER: │
│ │
│ As a returning user │
│ I want to sign in with my email and password │
│ So that I can access my saved preferences │
│ │
│ Acceptance Criteria: │
│ ☐ Login form with email and password fields │
│ ☐ "Sign in" button submits form │
│ ☐ Invalid credentials show error message │
│ ☐ Successful login redirects to dashboard │
│ ☐ Session persists for 7 days │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ BEFORE: "Make the app faster" │
│ │
│ AFTER: │
│ │
│ As a mobile user on slow connection │
│ I want the dashboard to load quickly │
│ So that I can check my tasks without waiting │
│ │
│ Acceptance Criteria: │
│ ☐ Dashboard loads in under 3 seconds on 3G │
│ ☐ Critical content visible in under 1 second │
│ ☐ Loading indicator shown during data fetch │
└─────────────────────────────────────────────────────────────┘
Story Refinement
Refinement Process
STORY REFINEMENT MEETING:
┌─────────────────────────────────────────────────────────────┐
│ │
│ PURPOSE: │
│ Get stories ready for sprint planning │
│ (Clear, sized, no major unknowns) │
│ │
│ FREQUENCY: Weekly, 1 hour │
│ │
│ ATTENDEES: │
│ • Product Owner (required) │
│ • Dev team members (2-3 minimum) │
│ • Designer (if relevant stories) │
│ │
│ PROCESS: │
│ │
│ 1. PO presents story (2 min) │
│ What and why │
│ │
│ 2. Team asks questions (5 min) │
│ Clarify requirements │
│ Identify unknowns │
│ │
│ 3. Discuss acceptance criteria (5 min) │
│ What does "done" look like? │
│ Edge cases? │
│ │
│ 4. Size if ready (2 min) │
│ Story points │
│ If too big, discuss splitting │
│ │
│ 5. Flag if not ready │
│ What's missing? │
│ Who needs to provide what? │
│ │
│ READY DEFINITION: │
│ ✓ Clear user and need │
│ ✓ Acceptance criteria defined │
│ ✓ Sized (story points) │
│ ✓ Small enough for sprint │
│ ✓ No major open questions │
└─────────────────────────────────────────────────────────────┘
Definition of Ready
STORY DEFINITION OF READY:
┌─────────────────────────────────────────────────────────────┐
│ │
│ A story is READY for sprint when: │
│ │
│ CLARITY: │
│ ☐ User story clearly stated │
│ ☐ Acceptance criteria defined │
│ ☐ Team understands the requirement │
│ │
│ SIZE: │
│ ☐ Estimated in story points │
│ ☐ Fits within one sprint │
│ ☐ Ideally 1-5 days of work │
│ │
│ DEPENDENCIES: │
│ ☐ No blocking dependencies │
│ ☐ External needs identified and scheduled │
│ │
│ DESIGN: │
│ ☐ UX/UI designs available (if needed) │
│ ☐ Design questions resolved │
│ │
│ TECHNICAL: │
│ ☐ Technical approach understood │
│ ☐ Major risks identified │
│ ☐ Spikes completed (if needed) │
│ │
│ IF NOT READY: │
│ • Don't pull into sprint │
│ • Identify what's missing │
│ • Assign owner to resolve │
│ • Revisit next refinement │
│ │
│ RULE: Only pull ready stories into sprint │
└─────────────────────────────────────────────────────────────┘