folio-org 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.
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 ✓
- Explain the value and the outcome, whoever the beneficiary is
- Make acceptance criteria specific and verifiable
- Cover material error scenarios and boundaries
- Keep binding constraints in Requirements
- Use consistent domain terminology
- Explain what each linked ticket contributes
Don'ts ✗
- Don't invent an end-user persona for technical or decision work
- Don't be vague — "improve performance" needs metrics
- Don't skip acceptance criteria
- Don't add sections the deliverable does not need
- Don't add "Out of Scope" for neighbouring topics that were never in scope
- Don't put test code, fixtures, or detailed test setup in the story
- Don't over-specify implementation — leave the "how" to developers
- 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.