User Stories & Acceptance Criteria — Product Management

User stories shift the conversation from features to outcomes. Instead of "add a filter button," a story says: "As a job seeker, I want to filter listings by salary, so I can focus only on roles within my range." The "so that" clause is the most important part — it captures the why, which is what you test against when deciding if the story is done.

Story Anatomy + Definition of Done

Central story card holds three components. Press Write Story to animate the As/I want/So that spheres out. Press Add Criteria to stack the acceptance checklist below.

drag — scroll to zoom

Code example

Gherkin acceptance criteria syntax and a story YAML template for your backlog tool.

USER STORY FORMATS

# Gherkin: Given-When-Then acceptance criteria
# Used by Cucumber, Cypress, Playwright for executable specs

Feature: Salary filter on job listings

  Background:
    Given the user is on the job search results page
    And there are 50 job listings with varying salaries

  Scenario: Filter by minimum salary
    When the user sets the minimum salary to "$80,000"
    Then only jobs with salary >= $80,000 are displayed
    And the result count updates to reflect the filter
    And a clear filter button appears

  Scenario: Clear salary filter
    Given a minimum salary filter of "$80,000" is active
    When the user clicks "Clear filters"
    Then all 50 listings are shown again
    And the salary filter input is reset to empty

  Scenario: No results match filter
    When the user sets the minimum salary to "$500,000"
    Then an empty state message is displayed
    And a suggestion to broaden the search is shown

# These scenarios ARE the acceptance criteria
# The story is done when all scenarios pass in CI
# User Story YAML Template
# Copy this into Linear, Jira, Notion, or your backlog tool

story:
  id: US-142
  title: "Salary filter on job listings"

  # The three-part user story format
  as_a: "job seeker browsing listings"
  i_want: "to filter listings by minimum salary"
  so_that: "I can focus only on roles within my compensation range"

  # INVEST criteria check
  invest:
    independent: true     # doesn't depend on US-141
    negotiable: true      # max salary filter is out of scope for now
    valuable: true        # 68% of users asked for this in research
    estimable: true       # team estimated 3 story points
    small: true           # fits in one sprint
    testable: true        # Gherkin scenarios above cover it

  acceptance_criteria:
    - "Filter shows only listings >= min salary"
    - "Result count updates immediately (no page refresh)"
    - "Clear filter button visible when filter is active"
    - "Empty state shown if no results match"
    - "Filter persists on page refresh (localStorage)"

  definition_of_done:
    - "All acceptance criteria pass in CI"
    - "Unit tests cover edge cases (0 results, max salary)"
    - "Accessible: keyboard navigable, ARIA labels correct"
    - "Design reviewed and approved"
    - "No regressions in existing search flow"

  story_points: 3
  priority: high
      

Key concepts

📝

User Story

As a — I want — So that

"As a [user type], I want to [action], so that [benefit]." The "so that" is the most important part — it captures the why, which prevents the team from shipping the letter of the request but missing the spirit.

✅

Acceptance Criteria

Given — When — Then — testable

Specific, testable conditions that must all be true before the story is accepted. Written as Gherkin (Given/When/Then) or plain bullets. The team agrees on them before work starts — not after.

💰

INVEST

Independent — Negotiable — Valuable — Estimable — Small — Testable

A quality checklist for stories. Independent: can be built without others. Negotiable: details can change. Valuable: user benefit is clear. Estimable: team can size it. Small: fits a sprint. Testable: you can verify it.

✔

Definition of Done

team agreement — quality bar — shipped

A checklist the whole team agrees on: tests pass, design approved, accessible, no regressions. A story is Done when every item is checked — not when the code is merged. Prevents "it works on my machine" from counting as done.

→ Roadmap & Prioritization Product Management — Algo3DVerse Metrics & KPIs ?