Write behavior-focused Agile user stories with BDD-style acceptance criteria. Use when defining features, clarifying requirements, creating development tickets, writing acceptance criteria, converting requirements to testable specs, or discussing user needs. Produces narrative-form stories with Given-When-Then scenarios.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Write behavior-focused Agile user stories with BDD-style acceptance criteria. Use when defining features, clarifying requirements, creating development tickets, writing acceptance criteria, converting requirements to testable specs, or discussing user needs. Produces narrative-form stories with Given-When-Then scenarios.
allowed-tools
["Read","Glob","Grep","Task"]
Writing Agile Stories
Reference for behavior-focused user stories using BDD principles. Stories describe desired behavior from the user's perspective, focusing on "what" rather than "how."
This is a non-interactive reference skill. Callers — direct users, orchestrator commands, and sub-agents — supply context and apply this guidance directly. Do not use AskUserQuestion. If context is thin, ask the user in plain prose for what's missing (see discovery-dimensions.md).
Quick Start
A complete story:
## Story: Customer Cancels Order Before Shipment
When customers change their mind about a purchase, they need to cancel it
and receive confirmation that their refund is being processed. This must
happen before the order ships, since the returns process applies afterward.
### Context
Available for orders in "confirmed" or "processing" status.
### Acceptance Criteria#### Scenario: Successful cancellation- Given a customer has an order in "confirmed" status
- When they request to cancel the order
- Then the order status changes to "cancelled"
And a refund is initiated for the full order amount
Given an order has left the warehouse
When the customer attempts to cancel
Then they are informed cancellation is unavailable
And they are directed to the returns process
-
#### Scenario: Order already shipped
-
-
-
-
This is an illustrative teaser. For the canonical version of this story with full scenarios, see templates.md. For additional worked examples with discovery summaries, see examples.md.
When This Skill Applies
Defining new features or user needs
Clarifying requirements before implementation
Creating tickets for development work
Converting vague requirements into testable specifications
User asks to "write a story" or "create acceptance criteria"
Core Principles
Behavior over Implementation — describe what users experience, not how it's built
Narrative over Template — use prose, NOT "As a [user], I want [feature], so that [benefit]"
Concrete over Abstract — use specific examples (Specification by Example)
Conversation Starter — stories facilitate discussion, not replace it
Ubiquitous Language — use terms from the problem domain, not technical jargon
Process Overview
The workflow has four phases. The story document has a Title, Narrative, Context, and Acceptance Criteria — discovery and review are workflow phases, not document sections.
The single most common defect. A scenario leaks if it references:
HTTP/API behavior ("the API returns 200", "POST /orders endpoint")
Database or storage ("the row is inserted", "the cache is invalidated", named tables)
UI elements ("the button is clicked", "the modal appears", "the page loads")
Code paths or services ("OrderService is called", "the handler fires")
Technical mechanisms ("retries 3 times", "publishes a Kafka event", "Redis is updated")
Farley's test: imagine the entire system replaced with a different implementation that fulfills the same behavior. The acceptance criteria should still make sense. If they would break, they describe implementation, not behavior.
The six dimensions: Actor, Trigger, Outcome, Constraints, Failure Modes, Domain Terms. See discovery-dimensions.md for definitions, examples, and what each missing dimension does to the story.
If the caller has supplied context (Jira/Linear ticket, product documentation, user-facing capability research, prior conversation), extract the dimensions from that context. If the dimensions are thin, ask the user in plain prose for the missing ones — open-ended discovery questions don't fit AskUserQuestion option chips.
Research Depth
Research stays at the behavior level. Do NOT read implementation code, trace call graphs, identify components/layers/integration points, or invoke deep-code agents (e.g., codebase-analyzer) to gather discovery dimensions. Stories operate on user-observable behavior; implementation knowledge belongs in planning, not story writing.
When supplied context is thin and you need more domain grounding, prefer in this order:
Use the capability-locator agent to inventory user-facing entry points (routes, pages, CLI commands, public APIs) at the capability level — never at the implementation level.
If all you have is code-level context, push back to the caller for behavior-level input rather than reverse-engineering behavior from implementation. See the "Implementation-Deep Discovery" entry in anti-patterns.md.
Discovery Output (internal scratchpad)
**Understanding**: [1-2 sentence summary]
**Actor**: [Who] | **Trigger**: [What prompts this]
**Outcome**: [What they achieve] | **Constraints**: [Rules]
**Failure Modes**: [What could go wrong]
**Domain Terms**: [Key vocabulary]
Phase 2: Story Drafting
Goal: Write a narrative-form story that captures the essence of the need.
Story Format
## Story: [Descriptive Title]
[2-4 sentence narrative describing:
- The user's situation
- The behavior they need
- The value they get
Written in domain language, present tense]
### Context
[When this behavior is relevant — the business preconditions]
For the canonical complete template and the discovery scratchpad template, see templates.md. For full worked examples (including discovery summaries), see examples.md.
Narrative Guidelines
DO:
Describe the situation that creates the need
Focus on observable behavior
Use domain language consistently
Keep it small enough for one iteration
DON'T:
Use "As a [user], I want [X], so that [Y]" template
Include implementation details (APIs, databases, buttons)
Write epic-sized stories
Use technical jargon outside the domain
Phase 3: Acceptance Criteria
Goal: Define testable scenarios using Given-When-Then format.
Scenario Types Required
Happy Path — the primary success scenario
Alternative Paths — valid variations with different outcomes
Failure Modes — how errors are handled gracefully
Criteria Format
### Acceptance Criteria#### Scenario: [Description]- Given [business context/state]
- When [user action or system event]
- Then [observable outcome]
- And [additional outcomes if needed]
Criteria Guidelines
DO:
Use business language in Given-When-Then
Focus on observable outcomes
Include concrete examples (specific values, not placeholders)
Make each scenario independently testable
DON'T:
Reference implementation details (see Implementation Leak above)
Goal: Validate the story against quality criteria.
Quality Checklist
Check
Anti-Pattern to Avoid
Behavior-focused
Implementation details, feature lists
Domain language only
"user clicks", "API returns"
Narrative form
"As a [user], I want..." template
Small & testable
Epic-sized, vague outcomes
Failure modes included
Only happy path scenarios
Scenarios independent
Scenarios requiring sequence
Verification Questions
Can a developer write tests directly from these scenarios?
Can a business stakeholder understand every term?
Is each scenario independently verifiable?
Are all failure modes covered?
Is the story small enough for one iteration?
Readability Polish
Stories are read by developers, designers, QA, and product. After verification, polish the prose portions only through the writing-for-humans skill. The acceptance criteria are testability-critical structured specs — leave them alone.
Polish scope (narrow):
The 2-4 sentence narrative paragraph under the story title
The single ### Context line
Do NOT polish:
The story title
### Acceptance Criteria header
#### Scenario: headers
Any Given / When / Then / And clause
Anything below the Context line
Critical preservation rules:
Domain terms ("ubiquitous language") must survive — do not substitute generic synonyms for domain vocabulary
Do not introduce UI/API/storage terms — the polish must not re-create the Implementation Leak
Do not insert "As a... I want... So that..." template phrasing
Invoke the writing-for-humans skill on the assembled story, passing the polish scope, do-not-polish list, and preservation rules above as the preserve/transform contract.
Replace the draft with the polished output. Spot-check that the acceptance criteria are byte-identical and that no UI/API terms snuck into the narrative.
Fallback: If writing-for-humans is unavailable (e.g., running inside another sub-agent, or generating many stories in a batch where the cost isn't justified), skip the polish and note "Readability polish deferred" in the handoff.
Final Presentation
When presenting the finished story, accompany it with the quality checklist showing which items pass.
