User story writer

User Story Writer

Overview

Turn a feature idea, requirement, or epic into well-formed user stories that a team can estimate, build, and verify. Every story states who wants what and why, passes the INVEST test, and ships with testable acceptance criteria.

Keywords: user story, agile, scrum, backlog, INVEST, acceptance criteria, Gherkin, given when then, story splitting, epic, vertical slice, definition of done, product backlog, refinement, grooming.

Workflow

1. Capture the intent. Identify the user/persona, the goal, and the underlying benefit. If the benefit is unclear, ask "so that what?" until you reach real value.
2. Write the story statement using the canonical form: As a <role>, I want <capability> so that <benefit>. Keep it to one sentence and one outcome.
3. Apply INVEST (see references/invest-checklist.md). If the story fails any letter — especially Small and Testable — split or sharpen it.
4. Split if too big. Use the splitting patterns in references/splitting-patterns.md (workflow steps, business rules, happy/error path, data variations, CRUD operations). Each slice must be a thin vertical slice that delivers value end-to-end, not a horizontal layer.
5. Write acceptance criteria in Gherkin: one Scenario per rule, covering the happy path, key edge cases, and at least one failure path. Use the template in templates/story-template.md.
6. Add a Definition of Done checklist items only if they are story-specific (e.g. "feature flag added", "analytics event fired"). Leave generic DoD to the team.
7. Self-review against references/invest-checklist.md and confirm every acceptance criterion is independently verifiable.

Decision Framework

Symptom	Action
Story has "and" in the goal	Split into separate stories
Can't estimate it	Too big or too vague — split or clarify
No clear user	It may be a task/enabler, not a story — label it as such
Acceptance criteria describe UI pixels	Re-focus on observable behavior, not implementation
"As a user" (generic)	Name the real persona; "user" hides differing needs

Worked Example

Epic: "Users can reset their password."

Story:

As a registered customer, I want to request a password reset link by email so that I can regain access when I've forgotten my password.

Acceptance Criteria:

Scenario: Request reset with a known email
  Given a registered account exists for "[email protected]"
  When she submits the reset form with "[email protected]"
  Then a reset email with a single-use link is sent within 1 minute
  And the page shows a neutral "If the email exists, we've sent a link" message

Scenario: Request reset with an unknown email
  Given no account exists for "[email protected]"
  When the reset form is submitted with "[email protected]"
  Then no email is sent
  And the same neutral confirmation message is shown (no account enumeration)

Scenario: Reset link expires
  Given a reset link issued more than 60 minutes ago
  When the user opens it
  Then they see "This link has expired" and can request a new one

See examples/checkout-epic-split.md for a full epic-to-stories breakdown.

Best Practices

• Write from the user's perspective, not the system's.
• One story = one outcome that fits comfortably in a sprint.
• Acceptance criteria describe observable behavior, not implementation.
• Always include at least one negative/edge scenario.
• Use neutral, security-aware wording for auth flows (no account enumeration).
• Keep the "so that" honest — if you can't name a benefit, question the story.

Common Pitfalls

• Horizontal slices ("build the database table") that deliver no user value alone.
• Generic personas ("as a user") masking conflicting needs.
• Untestable criteria ("it should be fast" — quantify it).
• Solutioning in the story ("add a Redis cache") instead of stating the need.
• Giant stories disguised by vague language; if you can't test it, you can't size it.