write-user-story

Write User Story

User Story Structure

Every story has three core sections, in order: Purpose/Overview, Requirements/Scope, and Acceptance Criteria. Choose supporting sections from the actual deliverable, not from the template. Determine the work type from the request and available context; ask a focused question only when an unresolved distinction would materially change the story.

Purpose/Overview states the outcome and its value. Requirements/Scope contains the capabilities, contracts, deliverables, and binding constraints. Acceptance Criteria states the smallest sufficient set of distinct, verifiable completion conditions. Technical enablers and discovery/policy work do not require an invented end-user persona.

Template

This skeleton is the whole story unless a supporting section earns its place.

## Purpose/Overview

[Outcome, value, and relevant context.]

## Requirements/Scope

1. [Required capability, contract, or deliverable, including binding constraints.]

## Acceptance Criteria

[Distinct verifiable completion conditions.
Use Given-When-Then for behavior or a concise checklist for contracts/deliverables.]

Acceptance Criteria

Use Given-When-Then for observable behavior, or a concise verifiable checklist when that expresses a technical contract or decision deliverable more clearly. Each criterion covers a distinct completion condition from the agreed scope. Cover material error and boundary behavior without expanding every configuration field into its own scenario. There is no target number of criteria: do not drop important conditions for brevity, and do not turn acceptance criteria into a test plan. Write each Given/When/Then/And as its own separate bullet line (- Given ..., - When ..., - Then ...), never as indented continuation lines under a single bullet - standard Markdown collapses soft-wrapped continuation lines into one run-on line, which renders as "Given abc When xyz Then 123" instead of the intended step-by-step format.

Task-Appropriate Verification

Work	Required behavior
User-facing/runtime change	Add Testing Guidance when it helps beyond the acceptance criteria. For a real UI workflow, Manual Testing with short steps and expected results is appropriate.
Backend/API/library change	Add Controlled Verification when useful: contract checks, a local harness, stubs, or controlled failure conditions. Naming the level of automated verification is fine without writing the tests. Never require breaking a shared or production deployment, or waiting for a real outage.
Pure discovery/policy/decision work	No runtime Testing Guidance. Verify the decision artifacts, trade-offs, recommendation, constraints, and the agreed review through Requirements and acceptance criteria. Do not write Testing Guidance: N/A.

Mixed work verifies each part that was actually requested in the way that fits it: the word "policy" alone does not remove testing for a runtime change that was genuinely requested.

Keep test code, mock configuration, fixture scripts, and implementation-plan-level test cases out of the story. This limits detail; it does not forbid naming automated or contract verification.

Conditional Sections

Add a section only when its condition holds.

• Out of Scope — only for a plausible alternative reading of this request that must be excluded, or a boundary the user stated explicitly. Neighbouring topics, future enhancements, and unrelated features are not reasons to add exclusions.
• Non-Functional Requirements — specific, significant security, compatibility, concurrency, integrity, or performance constraints. Not generic wishes for template completeness.
• Additional Notes — relevant non-binding context only. A commitment that affects correctness or acceptance belongs in Requirements, and in acceptance criteria when it is verifiable — never only in Notes.
• Technical Approach — optional high-level context. Do not invent an implementation, and do not delete an agreed technical constraint merely because it is technical.
• Related Links — every link kept has a clear role: dependency, prior behavior, parent scope, specification, or evidence. Do not list every neighbouring Jira key, and do not invent relationships.

Writing Guidelines

Persona format (when a user role applies)

As a [user persona/role]
I want [goal/desire]
So that [benefit/value]

Use this when a real user role is involved. For a technical enabler or a decision ticket, state the outcome and its value directly instead of inventing a persona.

INVEST Principles

• Independent — deliverable separately
• Negotiable — details can be refined
• Valuable — delivers clear value
• Estimable — team can estimate effort
• Small — completable within one sprint
• Testable — clear verification criteria

Best Practices

Do's ✓

1. Explain the value and the outcome, whoever the beneficiary is
2. Make acceptance criteria specific and verifiable
3. Cover material error scenarios and boundaries
4. Keep binding constraints in Requirements
5. Use consistent domain terminology
6. Explain what each linked ticket contributes

Don'ts ✗

1. Don't invent an end-user persona for technical or decision work
2. Don't be vague — "improve performance" needs metrics
3. Don't skip acceptance criteria
4. Don't add sections the deliverable does not need
5. Don't add "Out of Scope" for neighbouring topics that were never in scope
6. Don't put test code, fixtures, or detailed test setup in the story
7. Don't over-specify implementation — leave the "how" to developers
8. Don't leave a binding constraint in Additional Notes

Quick Reference Checklist

• Purpose clearly explains the value and context
• The chosen sections match the actual deliverable
• Requirements are specific, and every binding constraint is there
• Acceptance criteria are distinct, verifiable, and match the result type
• Material error and boundary conditions are covered
• Verification fits the work type, or is correctly absent for decision work
• Each optional section present is doing real work
• Each linked ticket's relationship is explained
• Story is sized for one sprint
• Technical approach is outlined only if needed, and not over-specified
• Non-functional requirements included only if significant

A missing optional section is not a defect.

For deep-dive guidance on each section, see references/section-details.md. For common pitfalls with before/after examples, see references/pitfalls.md. For a complete example story, see references/example.md. For JIRA markup conversion, see references/jira.md.