user-story

intent

Create clear, testable user stories that combine Mike Cohn's "As a / I want / so that" format with Gherkin acceptance criteria. Use this when translating user needs into development-ready work that stakeholders and engineers can act on immediately. A user story captures who benefits, what they're trying to do, why it matters, and how you'll verify success. it's not a feature spec or contract, it's a structured conversation starter that forces focus on user value, not just features or tech tasks.

inputs

Before writing a story, gather and document:

• User persona: specific role or segment (reference skills/proto-persona/SKILL.md). avoid generic "user"; use "trial user," "power user," "admin," etc.
• Problem statement: validated user need or pain point (reference skills/problem-statement/SKILL.md). if unclear, run discovery interviews first.
• Desired outcome: what success looks like from the user's perspective, not the product's.
• Constraints: technical, timeline, or scope limits that affect the story.
• Related epics or stories: parent feature or dependent work (reference skills/epic-hypothesis/SKILL.md for breakdown context).

optional helper: python3 scripts/user-story-template.py --persona "trial user" --action "log in with Google" --outcome "access the app without creating a new password" generates a consistent markdown stub (deterministic, no network access).

procedure

1. Validate context before writing

   • Input: user persona, problem statement, desired outcome, constraints.
   • Confirm you have specific answers (not generic descriptions). if missing, pause and run discovery work.
   • Output: documented context as notes or brief writeup.

2. Write the use case (Mike Cohn format)

   • Input: user persona, action the user takes, motivation/outcome.
   • Fill: "As a [persona], I want to [action], so that [outcome]."
   • Quality checks: (a) persona is specific (trial user, not "user"); (b) "I want to" describes user action, not feature you're building; (c) "so that" explains motivation, not restatement of action.
   • Output: single-sentence user story in Mike Cohn format.

3. Write acceptance criteria (Gherkin format)

   • Input: use case from step 2, scenario context, preconditions, user action, expected outcome.
   • Fill: scenario title, stack Given statements (initial context and preconditions), single When (event that triggers action), single Then (expected outcome).
   • Alignment check: When aligns with "I want to"; Then aligns with "so that."
   • Output: gherkin acceptance criteria block with scenario, given/and given stack, when, then.

4. Write a summary title

   • Input: use case and acceptance criteria from steps 2 and 3.
   • Create short, memorable title focused on user value, not feature name (e.g., "Enable Google login for trial users to reduce signup friction," not "Add Google OAuth button").
   • Output: single-line summary.

5. Validate and refine with team

   • Input: completed story (use case, acceptance criteria, summary).
   • Read aloud to product, engineering, and QA. ask: does everyone understand who, what, why? can QA write test cases from this? is the story too big (split needed)?
   • Check testability: is "Then" measurable and verifiable?
   • Output: refined story or decision to split (reference skills/user-story-splitting/SKILL.md).

decision points

• If persona is generic ("user") or unclear: add specificity or split into multiple stories by persona. avoid bundling trial users, power users, and admins into one story.
• If "so that" restates "I want to": dig deeper into user motivation. ask why they want the action. if no clear outcome, convert to engineering task instead.
• If acceptance criteria has multiple When or Then statements: this is a sign of scope creep. split into separate stories using skills/user-story-splitting/SKILL.md. one When/Then pair per story (or regroup if truly one scenario).
• If the story is a pure tech task (e.g., "refactor the database," "upgrade dependencies"): it's not a user story. use an engineering task or tech debt ticket instead. no user value, no user story.
• If acceptance criteria outcome is unmeasurable (e.g., "better experience," "faster," "improved"): add specifics. replace with measurable criteria (e.g., "page loads in under 2 seconds," "user sees success confirmation message").
• If context is missing (persona unknown, problem unvalidated, outcome unclear): pause writing and run discovery interviews or problem validation first. don't guess.

output contract

A completed user story in markdown format with these sections:

### User Story [ID]:

- **Summary:** [value-focused title, 1 sentence]

#### Use Case:
- **As a** [specific persona]
- **I want to** [user action]
- **so that** [desired outcome]

#### Acceptance Criteria:
- **Scenario:** [brief human-readable scenario]
- **Given:** [initial context/precondition]
- **and Given:** [additional preconditions, stack as needed]
- **When:** [triggering event, aligns with "I want to"]
- **Then:** [expected outcome, aligns with "so that"]

file location: typically in a backlog markdown file, wiki, or issue tracker (jira, github issues, linear, etc.).

data format: plain markdown, human-readable, no code or technical jargon in the story itself. acceptance criteria should be concrete and testable by qa.

quality gates: (a) one When and one Then per scenario (if multiple, story is too big); (b) "so that" is not a restatement; (c) persona is specific; (d) acceptance criteria outcome is measurable; (e) story fits on one screen or printed page (sign of right-sized scope).

outcome signal

you know the skill worked when:

• the story is understandable and actionable by product, engineering, and qa without follow-up questions.
• qa can immediately write test cases from the acceptance criteria without ambiguity.
• the story is small enough to fit in a sprint (typically 1-5 days of work). if it doesn't, you split it.
• the user motivation is clear. no one asks "why do we care about this?"
• the "so that" outcome is testable and verifiable. you can prove it happened.
• engineering can estimate the story and start work without clarification calls.

red flags that the skill didn't work:

• "As a user" with no persona specificity.
• "so that" restates the action ("I want to click save, so that I can save").
• multiple When or Then statements in one scenario.
• unmeasurable outcomes ("faster," "better").
• story is claimed too big for a sprint but no split plan exists.