QUICK ANSWER
What should a user story template include?
A user story template should include a stable story ID, title, specific actor and context, bounded need, observable outcome, value, acceptance examples, dependencies, risks, owner, status, and references to shared ready and done boundaries. It should also link back to product-level intent without replacing the PRD or treating story completion as UAT release signoff.
A useful user story turns one approved product intention into a bounded piece of backlog work. It names a specific actor and context, the need, an observable outcome, the value of that outcome, acceptance examples, dependencies, risks, and the conditions that make the story ready to start and done to review.
This downloadable pack includes Markdown, JSON, and two CSV views of five fictional stories for a support-request workflow. It keeps story IDs and references consistent, validates dependency cycles and risk ownership, and separates backlog decomposition from the product-level PRD and the business-level UAT release decision.
Complete the story without shrinking the product decision
Move from approved product intent to one observable backlog outcome. Keep references stable so the team can change a story without silently changing the parent product requirement or the release decision.
Link the story to approved product intent
Start with one product-requirement reference and one bounded behavior. The story may clarify implementation-sized work, but it must not redefine the user problem, product scope, non-goals, record lifecycle, policy, or release gates that belong in the PRD.
Sources: [prd-example], [user-story-pack]
Name the actor, context, need, and observable outcome
Use a specific role and situation instead of a generic user. Describe what the actor needs and what they or an external system can observe afterward. Keep interface choices and implementation internals out unless they are verified constraints of the product behavior.
Sources: [govuk-user-stories], [user-story-pack]
Write acceptance examples around important boundaries
Give each example a stable ID and a known context, one event, one observable result, and an evidence owner. Cover the relevant happy path plus invalid input, authorization, retry, stale conflict, partial failure, or recovery instead of using one vague checklist sentence.
Sources: [cucumber-gherkin], [user-story-pack]
Resolve dependencies, risks, and ready/done boundaries
Link every dependency and risk in both directions, reject dependency cycles, and keep one shared ready and done definition. Done means the story evidence is reviewable in the intended environment. It does not mean the PRD is approved, UAT passed, or the release and business outcome succeeded.
Sources: [user-story-pack], [prd-example]
What this user story pack owns
Use the pack after the product intent is bounded enough to decompose. It gives product, design, engineering, QA, security, and operations a small reviewable work record without replacing their accountable decisions.
Included
- Blank Markdown story template with actor, context, need, outcome, evidence, dependency, risk, ready, and done fields
- Completed fictional JSON pack with five stable user-story IDs and one linked product-requirement reference
- Story-level CSV and acceptance-example CSV generated directly from the JSON record
- Ten Given/When/Then examples spanning happy, invalid, retry, conflict, authorization, and recovery behavior
- Strict dependency-free validator, JSON Schema, negative tests, CSV parity checks, cycle detection, and deterministic ZIP builder
Not included
- The product problem, overall outcome, scope, non-goals, record model, policy, architecture, or release gates owned by the PRD
- Business acceptance, UAT execution, signoff authority, release authorization, deployment, monitoring evidence, or product-success decision
- A universal agile process, estimation method, sprint commitment, staffing plan, contract, legal review, security approval, accessibility conformance, or compliance certification
- Guaranteed delivery time, implementation quality, adoption, traffic, leads, sales, revenue, approval, or other business outcome
DOWNLOADABLE RESOURCE
Download the user story template pack
Use Markdown for discussion, JSON for a controlled source, and CSV for backlog or test review. The fictional Harbor Lantern example keeps every story, acceptance example, dependency, risk, and boundary reference traceable.
User story template pack
A backlog-level story pack with stable identities, observable outcomes, acceptance examples, dependency and risk links, and shared ready/done boundaries.
Format: Markdown, JSON, JSON Schema, two CSV views, and dependency-free Node.js validator/tests in one ZIP
Locally reproduced August 1, 2026. SHA-256: ba63145a72f6c362f768e803d4ed1892f6b1238457fade52618305923061a8cb
Included
- Blank Markdown user story template and boundary guidance
- Completed fictional JSON example and Draft 2020-12 JSON Schema
- Generated story and acceptance-example CSV files
- Strict validator with malformed-input, reference, duplicate-edge, cycle, risk, privacy, boundary, and unsupported-claim checks
- Reproducible allowlisted ZIP builder and byte-parity test
Verification boundary
The archive allowlist, exact extracted bytes, repeatable SHA-256, JSON and CSV parity, closed object shapes, stable IDs, valid date and version, actor and context, observable outcome, acceptance coverage, bidirectional references, duplicate-free dependency graph, risk ownership, ready/done references, fictional-data and privacy boundaries, and malformed cases were checked locally. Public availability and the correctness of an adapted story remain separate gates.
Four user story shapes for different implementation risks
The sentence format stays small, but the acceptance and dependency detail changes with the dominant risk. These patterns show how to make one outcome reviewable without copying fictional policy into a real product.
Public or signed-in intake story
Use when: A person submits a form that must create one durable record before any optional provider delivery.
Name the actor, form version, required fields, server validation, save result, visible request ID, retry identity, and operator evidence. Keep notification or CRM delivery outside the durable save result.
Structure
- Happy and invalid-input examples prove one complete record or no record
- Retry and partial-failure examples separate durable save from optional delivery
Watch for: Do not show success before the durable record exists or imply that a provider delivered, qualified, or acted on the submission.
Sources: [govuk-user-stories], [cucumber-gherkin], [user-story-pack]
Versioned workflow transition story
Use when: Two people can review or change the same record and a stale update must not overwrite a newer decision.
Make the expected version, allowed transition, actor permission, conflict response, reload path, audit event, and next reviewed action observable in separate acceptance examples.
Structure
- One example accepts the first valid transition and records the next version
- One example returns the current state for a stale writer without silent overwrite
Watch for: A timestamp alone is not a conflict policy. Name which version is authoritative and who decides after a conflict.
Sources: [cucumber-gherkin], [user-story-pack]
Cross-account authorization story
Use when: A private record belongs to one workspace, customer, team, or tenant and another ordinary account must be denied.
Use two ordinary accounts, derive scope from the signed-in session, and assert read, list, update, export, response shape, and audit behavior instead of testing only whether a button is hidden.
Structure
- Authorized example proves the intended actor can observe the record outcome
- Denied example proves another account learns no protected record detail
Watch for: A guessed record ID, hidden URL, or client-provided workspace ID is not authorization evidence.
Sources: [user-story-pack], [prd-example]
Provider-backed attempt story
Use when: A durable product result may trigger email, chat, payment, storage, search, or another external provider attempt.
Keep the business record and provider attempt as separate identities. Write acceptance for credentials, timeout, retry, duplicate or out-of-order callbacks, reconciliation, degraded behavior, and recovery where those risks apply.
Structure
- Business-state example proves the core record without claiming provider completion
- Provider examples prove attempt state, retry identity, reconciliation, and target smoke separately
Watch for: A local handler or queued attempt does not prove provider approval, delivery, payment, indexing, or production behavior.
Sources: [user-story-pack], [prd-example]
Decide whether the story is ready to enter implementation
A story is ready when the team can build and test one bounded outcome without inventing product policy. Use these stop rules before a short sentence becomes a hidden specification.
The actor, context, need, or observable outcome is generic
Choose: Keep the story in backlog and rewrite it around one role, situation, behavior, and visible result.
Tradeoff: The discussion takes longer now, but the team avoids implementing several incompatible interpretations.
The story changes product scope, policy, records, or release gates
Choose: Update and review the PRD or decision record first, then link the story to the accepted version.
Tradeoff: Backlog work pauses while the product decision catches up, preserving the product-level contract.
Acceptance describes only a happy screen or internal database state
Choose: Add observable examples for the important invalid, authorization, retry, conflict, partial-failure, or recovery boundary.
Tradeoff: The story may split into smaller slices, but completion becomes testable rather than subjective.
A dependency is circular or a risk has no accountable owner
Choose: Resolve the graph or ownership before moving the story to ready. Split shared prerequisites into a named predecessor where useful.
Tradeoff: The apparent start date moves, but blocked work and hidden sequencing become visible.
The team treats done as UAT signoff or release approval
Choose: Keep story evidence, business acceptance, release gates, target smoke, and product outcomes as separate records and decisions.
Tradeoff: There are more explicit gates, but no local completion label can silently authorize a release.
START WITH ONE OBSERVABLE OUTCOME
Download the story pack and split the first product slice
Copy the blank Markdown block or edit the JSON and CSV files. Replace every fictional actor, policy, risk, and result with reviewed product evidence before moving a story to ready.
Download the user story packThe ZIP was reproduced locally. Public availability must be verified after deployment.
Start with the product requirements document templateUse the PRD owner when the problem, product scope, record lifecycle, policy, or release gates still need a product-level decision.
Limits to review before adapting the template
The pack makes backlog records consistent and traceable. It cannot decide whether the parent product requirement is valuable, approved, safe, complete, or ready to release.
- A structural validator can check fields, references, graph cycles, CSV parity, and explicit boundaries. It cannot prove product value, usability, implementation correctness, or evidence quality.
- The fictional Harbor Lantern workspace, actors, request IDs, dates, risks, policies, and outcomes are examples, not production data or recommended policy.
- Ready and done definitions must be reviewed for the team, product, environment, risk, and release process. Copying them does not create accountability.
- Acceptance examples may inform automated or manual tests, but a written Given/When/Then statement is not proof that the behavior was exercised.
- The template is not legal, security, privacy, accessibility, employment, medical, financial, compliance, procurement, or other professional approval.
- This ordinary informational resource does not grant AI signup credits. The linked commercial page follows its own current eligibility rules.
Sources and verification record
Primary public guidance supports the actor, goal, acceptance-example, and observable-outcome patterns. The same-release artifact and PRD example support this pack's traceability and product-level boundary.
[user-story-pack] Playcode:Completed fictional user story example
Checked August 1, 2026. Supports: The five stable stories, ten acceptance examples, three dependency edges, four risks, shared ready/done definitions, CSV parity, and explicit PRD and UAT boundary. Public availability remains unverified until deployment.
[govuk-user-stories] Government Digital Service:Writing user stories
Checked August 1, 2026. Supports: Primary guidance that a story should identify the actor, what the person needs, why the person needs it, and outcome-focused acceptance criteria. It does not prescribe this artifact or ready/done policy.
[cucumber-gherkin] Cucumber:Gherkin Reference
Checked August 1, 2026. Supports: The Given context, When event, and Then observable outcome structure used for the acceptance examples. A written example is not evidence that a step definition or end-to-end flow was executed.
[prd-example] Playcode:Completed product requirements document example
Checked August 1, 2026. Supports: The separate product-level contract for problem, scope, non-goals, records, requirements, acceptance, dependencies, risks, decisions, and release gates. It does not make a linked story or release approved.
User story template questions
What is the standard format for a user story?
A common format is: As a specific actor, in a relevant context, I need one bounded behavior so that I can observe a useful outcome. Add stable identity, acceptance examples, dependencies, risks, owner, and ready/done references when the story enters a real backlog.
What is the difference between a user story and a PRD?
A PRD owns the product-level problem, outcome, scope, non-goals, records, behavior, dependencies, risks, decisions, and release gates. A user story decomposes that accepted intent into one backlog-sized outcome and its evidence. Change the PRD first when a story would redefine product policy or scope.
Should acceptance criteria use Given, When, and Then?
They can. Given/When/Then is useful when it makes the initial context, event, and observable result precise. A short outcome checklist can also work. Use whichever form reduces ambiguity, then link actual evidence rather than treating written criteria as a passing test.
What belongs in a definition of ready?
Include the minimum information needed to implement without inventing policy: actor, context, bounded need, observable outcome, linked product intent, acceptance examples, dependencies, risks, decision owner, and relevant evidence constraints. Keep a story blocked when a product-policy question is unresolved.
What belongs in a definition of done?
Require current evidence for the linked acceptance examples in the intended environment, plus relevant authorization, invalid-input, retry, conflict, recovery, monitoring, and rollback ownership. Done should not automatically mean PRD approval, UAT signoff, deployment authorization, adoption, or business success.
Can Playcode build an app from user stories?
Playcode can build and run a web app from a reviewed brief and a coherent set of stories. Include the product-level records, roles, states, provider boundaries, and release gates alongside the backlog items. Real credentials, policy review, target-environment tests, UAT, and release authorization remain separate work.
TURN REVIEWED STORIES INTO WORKING SOFTWARE
Give Playcode the product contract and the first bounded stories
Describe the records, roles, states, acceptance examples, failure boundaries, and stop gates in plain language. Build the smallest coherent web-app slice, then test the real target before expanding it.
Explore the AI app builderThis article does not grant AI signup credits. No delivery-time, approval, UAT, product-success, or native provider-integration guarantee is claimed.