Actionable User Stories | INVEST Criteria Guide
Write user stories developers can immediately implement using INVEST criteria and acceptance criteria templates. GitScrum bridges requirements and working software.
16 min read
A well-written user story is the difference between a developer asking clarifying questions for days and immediately starting productive work. This guide covers the complete framework for creating user stories that are truly actionable—clear enough to code from, small enough to complete in a sprint, and valuable enough to matter to users.
The Anatomy of Actionable Stories
What makes a story actionable:
| Element | Purpose | Example |
|---|---|---|
| User role | Who benefits | "As a project manager..." |
| Action | What they want to do | "...I want to export reports..." |
| Benefit | Why it matters | "...so I can share progress with stakeholders" |
| Acceptance criteria | Definition of done | Given/When/Then statements |
| Size | Sprint-completable | 1-8 story points typically |
The User Story Format
Standard Template
USER STORY STRUCTURE:
┌─────────────────────────────────────────────────────────────┐
│ TITLE: [Verb] + [Object] + [Context] │
│ Example: "Export Sprint Report to PDF" │
├─────────────────────────────────────────────────────────────┤
│ │
│ USER STORY: │
│ As a [type of user], │
│ I want to [perform action], │
│ So that [achieve benefit]. │
│ │
│ EXAMPLE: │
│ As a project manager, │
│ I want to export my sprint report as a PDF, │
│ So that I can share progress with stakeholders │
│ who don't have GitScrum access. │
│ │
├─────────────────────────────────────────────────────────────┤
│ ACCEPTANCE CRITERIA: │
│ │
│ ✓ Given I am on the Sprint Report page │
│ When I click "Export to PDF" │
│ Then a PDF downloads with all visible report data │
│ │
│ ✓ Given the report has charts │
│ When I export to PDF │
│ Then charts render correctly in the PDF │
│ │
│ ✓ Given the sprint has 100+ tasks │
│ When I export to PDF │
│ Then export completes within 30 seconds │
│ │
├─────────────────────────────────────────────────────────────┤
│ TECHNICAL NOTES (optional): │
│ - Use existing report data endpoint │
│ - PDF library: jsPDF or similar │
│ - Include company logo from settings │
│ │
├─────────────────────────────────────────────────────────────┤
│ DEPENDENCIES: │
│ - Requires: Sprint Report UI (completed) │
│ - Blocked by: None │
│ │
├─────────────────────────────────────────────────────────────┤
│ ESTIMATE: 5 story points │
│ PRIORITY: Medium │
│ LABELS: Feature, Reports, Sprint-24 │
│ │
└─────────────────────────────────────────────────────────────┘
The INVEST Criteria
Evaluating Story Quality
INVEST CHECKLIST:
┌─────────────────────────────────────────────────────────────┐
│ I - INDEPENDENT │
├─────────────────────────────────────────────────────────────┤
│ Can be developed without depending on other stories │
│ │
│ ❌ BAD: "As a user, I want the login button to work" │
│ (depends on auth system, session management, etc.) │
│ │
│ ✅ GOOD: "As a user, I want to log in with email/password" │
│ (complete feature, self-contained) │
│ │
│ TEST: Can this story be developed and deployed alone? │
│ │
├─────────────────────────────────────────────────────────────┤
│ N - NEGOTIABLE │
├─────────────────────────────────────────────────────────────┤
│ Details can be discussed and refined with the team │
│ │
│ ❌ BAD: "Implement login exactly as shown in wireframe v2.3"│
│ (too prescriptive, no room for improvement) │
│ │
│ ✅ GOOD: "Users need secure, quick access to their account" │
│ (outcome-focused, implementation negotiable) │
│ │
│ TEST: Could a developer suggest a better approach? │
│ │
├─────────────────────────────────────────────────────────────┤
│ V - VALUABLE │
├─────────────────────────────────────────────────────────────┤
│ Delivers value to user or business (not just technical) │
│ │
│ ❌ BAD: "Refactor database connection pool" │
│ (technical task, no user value stated) │
│ │
│ ✅ GOOD: "Improve page load time from 3s to under 1s" │
│ (user experiences faster loading) │
│ │
│ TEST: Would a user/stakeholder care about this? │
│ │
├─────────────────────────────────────────────────────────────┤
│ E - ESTIMABLE │
├─────────────────────────────────────────────────────────────┤
│ Team can estimate effort with reasonable confidence │
│ │
│ ❌ BAD: "Integrate with third-party analytics" │
│ (too vague - which provider? what data?) │
│ │
│ ✅ GOOD: "Send page view events to Google Analytics 4" │
│ (specific, known scope) │
│ │
│ TEST: Can the team agree on story points within 5 min? │
│ │
├─────────────────────────────────────────────────────────────┤
│ S - SMALL │
├─────────────────────────────────────────────────────────────┤
│ Completable within a single sprint (ideally 1-3 days work) │
│ │
│ ❌ BAD: "As a user, I want a complete dashboard" │
│ (too large - weeks of work) │
│ │
│ ✅ GOOD: "As a user, I want to see my task count widget" │
│ (one component, few days) │
│ │
│ TEST: Can one developer complete this in 3 days or less? │
│ │
├─────────────────────────────────────────────────────────────┤
│ T - TESTABLE │
├─────────────────────────────────────────────────────────────┤
│ Clear criteria for determining when story is done │
│ │
│ ❌ BAD: "Make the UI more intuitive" │
│ (subjective, no clear pass/fail) │
│ │
│ ✅ GOOD: "User can complete checkout in 3 clicks or less" │
│ (measurable, verifiable) │
│ │
│ TEST: Can you write an acceptance test for this? │
│ │
└─────────────────────────────────────────────────────────────┘
Writing Acceptance Criteria
Given-When-Then Format
ACCEPTANCE CRITERIA TEMPLATE:
┌─────────────────────────────────────────────────────────────┐
│ STRUCTURE: │
│ │
│ Given [precondition/context] │
│ When [action is performed] │
│ Then [expected result] │
│ │
├─────────────────────────────────────────────────────────────┤
│ EXAMPLE STORY: Password Reset │
├─────────────────────────────────────────────────────────────┤
│ │
│ HAPPY PATH: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Given I am on the login page ││
│ │ When I click "Forgot password" ││
│ │ Then I see a form to enter my email ││
│ │ ││
│ │ Given I have entered my registered email ││
│ │ When I click "Send reset link" ││
│ │ Then I see confirmation message ││
│ │ And I receive email with reset link within 2 minutes ││
│ │ ││
│ │ Given I clicked the reset link in email ││
│ │ When I enter new password meeting requirements ││
│ │ Then my password is updated ││
│ │ And I can log in with new password ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ ERROR CASES: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Given I enter an unregistered email ││
│ │ When I click "Send reset link" ││
│ │ Then I see same confirmation (security - no email leak) ││
│ │ ││
│ │ Given I have a reset link older than 24 hours ││
│ │ When I click the link ││
│ │ Then I see "Link expired" message ││
│ │ And I can request a new link ││
│ │ ││
│ │ Given I enter password not meeting requirements ││
│ │ When I try to submit ││
│ │ Then I see specific requirement that failed ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ EDGE CASES: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Given I request password reset twice ││
│ │ When I use the first link ││
│ │ Then only the second (latest) link works ││
│ │ ││
│ │ Given I am already logged in ││
│ │ When I access reset password page ││
│ │ Then I am redirected to change password (not reset) ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
Criteria Completeness Checklist
ACCEPTANCE CRITERIA COVERAGE:
┌─────────────────────────────────────────────────────────────┐
│ VERIFY ALL SCENARIOS ARE COVERED: │
├─────────────────────────────────────────────────────────────┤
│ │
│ ☐ HAPPY PATH │
│ Main use case works as expected │
│ │
│ ☐ ERROR HANDLING │
│ What happens when things go wrong │
│ - Invalid input │
│ - Network failure │
│ - Server error │
│ │
│ ☐ EDGE CASES │
│ Boundary conditions │
│ - Empty states │
│ - Maximum limits │
│ - Concurrent actions │
│ │
│ ☐ PERMISSIONS │
│ Who can/cannot do this │
│ - Admin vs. regular user │
│ - Owner vs. team member │
│ - Logged in vs. anonymous │
│ │
│ ☐ PERFORMANCE │
│ Response time expectations │
│ - Page load time │
│ - API response time │
│ - Batch operation limits │
│ │
│ ☐ ACCESSIBILITY │
│ Inclusive design requirements │
│ - Keyboard navigation │
│ - Screen reader support │
│ - Color contrast │
│ │
└─────────────────────────────────────────────────────────────┘
Story Splitting Techniques
Vertical Slicing
SPLITTING LARGE STORIES:
┌─────────────────────────────────────────────────────────────┐
│ BEFORE: Epic-sized story (too big) │
├─────────────────────────────────────────────────────────────┤
│ │
│ "As a user, I want to manage my profile settings" │
│ Estimate: 40 points (way too big!) │
│ │
├─────────────────────────────────────────────────────────────┤
│ AFTER: Vertical slices (right-sized) │
├─────────────────────────────────────────────────────────────┤
│ │
│ Story 1: View Profile (3 pts) │
│ "As a user, I want to view my current profile info" │
│ │
│ Story 2: Edit Name (2 pts) │
│ "As a user, I want to change my display name" │
│ │
│ Story 3: Upload Avatar (5 pts) │
│ "As a user, I want to upload a profile picture" │
│ │
│ Story 4: Change Email (5 pts) │
│ "As a user, I want to change my email with verification" │
│ │
│ Story 5: Change Password (3 pts) │
│ "As a user, I want to change my password" │
│ │
│ Story 6: Notification Preferences (3 pts) │
│ "As a user, I want to control email notifications" │
│ │
│ Story 7: Delete Account (5 pts) │
│ "As a user, I want to delete my account permanently" │
│ │
│ TOTAL: 26 points across 7 stories │
│ Each story: Independently deployable, testable, valuable │
│ │
└─────────────────────────────────────────────────────────────┘
Splitting Strategies
STORY SPLITTING PATTERNS:
┌─────────────────────────────────────────────────────────────┐
│ 1. BY WORKFLOW STEPS │
├─────────────────────────────────────────────────────────────┤
│ Original: "User checkout process" │
│ Split: │
│ ├── Add items to cart │
│ ├── Enter shipping address │
│ ├── Select shipping method │
│ ├── Enter payment info │
│ ├── Review and confirm │
│ └── Order confirmation email │
│ │
├─────────────────────────────────────────────────────────────┤
│ 2. BY OPERATIONS (CRUD) │
├─────────────────────────────────────────────────────────────┤
│ Original: "Manage projects" │
│ Split: │
│ ├── View list of projects │
│ ├── Create new project │
│ ├── Edit project details │
│ ├── Archive project │
│ └── Delete project │
│ │
├─────────────────────────────────────────────────────────────┤
│ 3. BY DATA TYPES │
├─────────────────────────────────────────────────────────────┤
│ Original: "Import data from file" │
│ Split: │
│ ├── Import CSV format │
│ ├── Import Excel format │
│ ├── Import JSON format │
│ └── Import from Google Sheets │
│ │
├─────────────────────────────────────────────────────────────┤
│ 4. BY USER TYPES │
├─────────────────────────────────────────────────────────────┤
│ Original: "Dashboard for all users" │
│ Split: │
│ ├── Admin dashboard (all data) │
│ ├── Manager dashboard (team data) │
│ ├── Developer dashboard (my work) │
│ └── Guest dashboard (public data) │
│ │
├─────────────────────────────────────────────────────────────┤
│ 5. BY HAPPY PATH vs. EDGE CASES │
├─────────────────────────────────────────────────────────────┤
│ Original: "Upload file with validation" │
│ Split: │
│ ├── Upload valid file (happy path) │
│ ├── Handle file too large │
│ ├── Handle invalid file type │
│ └── Handle upload interruption/retry │
│ │
├─────────────────────────────────────────────────────────────┤
│ 6. BY PLATFORM/DEVICE │
├─────────────────────────────────────────────────────────────┤
│ Original: "Responsive photo gallery" │
│ Split: │
│ ├── Desktop layout │
│ ├── Tablet layout │
│ └── Mobile layout │
│ │
└─────────────────────────────────────────────────────────────┘
User Personas in Stories
Defining User Types
USER PERSONA EXAMPLES:
┌─────────────────────────────────────────────────────────────┐
│ GITSCRUM USER TYPES │
├─────────────────────────────────────────────────────────────┤
│ │
│ AGENCY OWNER (Admin) │
│ ├── Full access to all projects │
│ ├── Billing and subscription management │
│ ├── User management │
│ └── Company-wide reports │
│ │
│ PROJECT MANAGER │
│ ├── Create and manage projects │
│ ├── Sprint planning and tracking │
│ ├── Team assignment │
│ └── Client communication │
│ │
│ DEVELOPER │
│ ├── View assigned tasks │
│ ├── Update task status │
│ ├── Track time │
│ └── Participate in discussions │
│ │
│ CLIENT (External) │
│ ├── View project progress │
│ ├── Submit feedback via Form2Task │
│ ├── Approve deliverables │
│ └── Limited visibility (ClientFlow) │
│ │
├─────────────────────────────────────────────────────────────┤
│ USING PERSONAS IN STORIES: │
├─────────────────────────────────────────────────────────────┤
│ │
│ ❌ VAGUE: "As a user, I want to see reports" │
│ │
│ ✅ SPECIFIC: │
│ "As an agency owner, I want to see revenue by project..." │
│ "As a project manager, I want to see sprint burndown..." │
│ "As a developer, I want to see my time logged this week..." │
│ "As a client, I want to see my project's progress..." │
│ │
└─────────────────────────────────────────────────────────────┘
Common Anti-Patterns
Stories to Avoid
USER STORY ANTI-PATTERNS:
┌─────────────────────────────────────────────────────────────┐
│ ❌ TECHNICAL TASK DISGUISED AS STORY │
├─────────────────────────────────────────────────────────────┤
│ │
│ BAD: "As a developer, I want to refactor the auth module" │
│ │
│ PROBLEM: Developer isn't the end user, no user value │
│ │
│ BETTER: Break into valuable stories OR make it a task: │
│ - Story: "As a user, I want login to be faster (<2s)" │
│ - Task: "Refactor auth module (enables login speed story)" │
│ │
├─────────────────────────────────────────────────────────────┤
│ ❌ SOLUTION-FOCUSED (Not problem-focused) │
├─────────────────────────────────────────────────────────────┤
│ │
│ BAD: "As a user, I want a dropdown menu for categories" │
│ │
│ PROBLEM: Prescribes specific implementation │
│ │
│ BETTER: "As a user, I want to quickly filter by category │
│ so I can find relevant items faster" │
│ (Team can propose dropdown, tags, search, etc.) │
│ │
├─────────────────────────────────────────────────────────────┤
│ ❌ EPIC DISGUISED AS STORY │
├─────────────────────────────────────────────────────────────┤
│ │
│ BAD: "As a user, I want a complete project management tool" │
│ │
│ PROBLEM: Months of work, impossible to estimate │
│ │
│ BETTER: Break into specific, valuable features │
│ │
├─────────────────────────────────────────────────────────────┤
│ ❌ MISSING "SO THAT" (No value statement) │
├─────────────────────────────────────────────────────────────┤
│ │
│ BAD: "As a user, I want to export data" │
│ │
│ PROBLEM: Why? What problem does this solve? │
│ │
│ BETTER: "As a project manager, I want to export data │
│ so that I can create custom reports in Excel" │
│ │
├─────────────────────────────────────────────────────────────┤
│ ❌ VAGUE ACCEPTANCE CRITERIA │
├─────────────────────────────────────────────────────────────┤
│ │
│ BAD: "Works correctly", "Fast", "User-friendly" │
│ │
│ PROBLEM: Not testable, subjective │
│ │
│ BETTER: Specific, measurable criteria │
│ - "Returns results in < 500ms" │
│ - "Form submits without page reload" │
│ - "Accessible with keyboard only" │
│ │
└─────────────────────────────────────────────────────────────┘
GitScrum Task Creation
Story to Task Mapping
CREATING STORIES IN GITSCRUM:
┌─────────────────────────────────────────────────────────────┐
│ TASK FIELDS MAPPING │
├─────────────────────────────────────────────────────────────┤
│ │
│ TITLE: │
│ Format: [Action] [Object] [Context] │
│ Example: "Export Sprint Report to PDF" │
│ │
│ DESCRIPTION: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ## User Story ││
│ │ As a **project manager**, I want to **export sprint ││
│ │ reports as PDF** so that I can **share progress with ││
│ │ stakeholders who don't have GitScrum access**. ││
│ │ ││
│ │ ## Acceptance Criteria ││
│ │ - [ ] Export button visible on Sprint Report page ││
│ │ - [ ] PDF includes all visible charts and tables ││
│ │ - [ ] Export completes within 30 seconds for 100+ tasks ││
│ │ - [ ] PDF is downloadable and shareable ││
│ │ ││
│ │ ## Technical Notes ││
│ │ - Use existing report data endpoint ││
│ │ - Consider jsPDF library ││
│ │ - Include company logo from project settings ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ STORY POINTS: 5 │
│ PRIORITY: Medium │
│ LABELS: Feature, Reports, Sprint-24 │
│ ASSIGNEE: Set during sprint planning │
│ DUE DATE: End of sprint │
│ │
└─────────────────────────────────────────────────────────────┘
Story Refinement Process
Pre-Planning Checklist
DEFINITION OF READY:
┌─────────────────────────────────────────────────────────────┐
│ BEFORE A STORY ENTERS SPRINT PLANNING: │
├─────────────────────────────────────────────────────────────┤
│ │
│ ☐ USER STORY COMPLETE │
│ - Clear user role identified │
│ - Action described (what user wants to do) │
│ - Value stated (why it matters) │
│ │
│ ☐ ACCEPTANCE CRITERIA DEFINED │
│ - Happy path covered │
│ - Error cases identified │
│ - Edge cases considered │
│ │
│ ☐ SIZED APPROPRIATELY │
│ - Team has estimated (story points) │
│ - Fits within single sprint │
│ - No unknown dependencies │
│ │
│ ☐ DEPENDENCIES CLEARED │
│ - No blocking work from other teams │
│ - Required APIs/services available │
│ - Design/UX assets ready │
│ │
│ ☐ QUESTIONS ANSWERED │
│ - Product owner clarified requirements │
│ - Technical spikes completed if needed │
│ - No open questions blocking start │
│ │
│ IF ANY ☐ IS UNCHECKED: │
│ → Story goes to backlog refinement, not sprint │
│ │
└─────────────────────────────────────────────────────────────┘