Purpose
Turn a rough feature description or user story into a rigorous, testable set of acceptance criteria — covering the happy path, edge cases, error states, and permissions — so developers know exactly what to build and QA knows exactly what to verify. Eliminates ambiguous stories that get bounced back in refinement or fail review after the work is "done."
When to Use
Invoke this skill when the user asks to:
- Write acceptance criteria for a user story or feature
- Turn a feature description into Given/When/Then scenarios
- Refine or "make testable" a vague backlog item before sprint planning
- Add edge cases and error handling to an existing story
- Prepare a story for a refinement or grooming session
- Generate a Definition of Done for a specific feature
Inputs Required
Before starting, collect:
- User story or feature description: The story ("As a… I want… so that…") or a plain-language description of what's being built
- User roles/personas: Who interacts with this feature and their permission levels
- System context: What system, screen, or workflow this lives in (e.g., checkout flow, admin dashboard, API endpoint)
- Known business rules: Validation rules, limits, thresholds, or logic that must hold
- Data/state dependencies: Preconditions, existing data, or upstream states the feature relies on
- Non-functional requirements: Performance, accessibility, security, or compliance expectations (if any)
- Out of scope: What this story explicitly does not cover
If roles or business rules aren't provided, infer reasonable defaults from the story and flag each assumption inline so the Product Owner can confirm.
Instructions
Step 1: Restate and Sharpen the Story
Rewrite the story in canonical form: "As a [role], I want [capability], so that [benefit]." If the provided story is missing the benefit or role, fill it in and mark it as an assumption. Confirm the story is a single, deliverable slice — if it bundles multiple features, note that it should be split and list the suggested split.
Step 2: Identify the Scenario Set
Before writing criteria, enumerate the scenarios this feature must cover across these categories:
- Happy path: The primary success flow
- Alternate paths: Valid variations (different roles, optional inputs, alternate entry points)
- Boundary/edge cases: Empty states, maximums, minimums, first-time use, concurrent actions
- Error handling: Invalid input, failed dependencies, timeouts, unauthorized access
- Permissions/roles: What each role can and cannot do
List the scenario titles first, then expand each into full criteria in Step 3.
Step 3: Write Given/When/Then Criteria
For each scenario, write one or more criteria in Gherkin format:
- Given [initial context/precondition]
- When [the action or event]
- Then [the expected, observable outcome]
- Use And / But for compound conditions
Rules for well-formed criteria:
- Each Then must be observable and verifiable — no "the system should work correctly"
- One behavior per scenario — split compound outcomes into separate scenarios
- State concrete values, not vague qualifiers ("within 2 seconds," not "quickly"; "displays an inline error 'Email is required'," not "shows an error")
- Preconditions in Given must be independently reproducible by QA
- Cover the negative case for every rule (if there's a validation, there's a scenario for violating it)
Step 4: Capture Non-Functional Criteria
Add explicit criteria for any applicable non-functional requirements: performance thresholds, accessibility (e.g., keyboard-navigable, screen-reader labels), security (authorization checks, data handling), and audit/logging. Only include categories relevant to the feature — do not pad with generic entries.
Step 5: Build the Definition of Done Checklist
Produce a feature-specific DoD checklist that goes beyond the acceptance criteria: code reviewed, unit/integration tests added, documentation updated, feature flagged if applicable, analytics/events instrumented, and product owner sign-off. Tailor items to what this specific feature actually requires.
Step 6: Flag Open Questions
List any ambiguities, missing business rules, or dependencies that must be resolved before development. Frame each as a direct question the Product Owner can answer in refinement.
Output Format
- Structure: Sharpened story → scenario list → full Given/When/Then criteria grouped by category → non-functional criteria → Definition of Done checklist → open questions
- Length: 500–900 words, scaling with feature complexity (typically 8–15 scenarios)
- Format: Structured document — Gherkin blocks for criteria, checkboxes for the DoD, numbered list for open questions
- Sections: User Story → Scenarios Covered → Acceptance Criteria (by category) → Non-Functional Criteria → Definition of Done → Open Questions
- Tone: Precise and unambiguous — written for engineers and QA, not for a pitch deck. Every statement testable.
Quality Checklist
Before delivering output, verify:
- [ ] Every criterion follows Given/When/Then structure with an observable Then
- [ ] At least one happy path, one edge case, and one error-handling scenario are present
- [ ] Every business rule has both a passing and a failing scenario
- [ ] No vague qualifiers ("fast," "correctly," "properly") appear in any Then clause
- [ ] Permission scenarios exist for each role provided
- [ ] All inferred assumptions are flagged inline, and open questions are listed separately
- [ ] The Definition of Done items are specific to this feature, not boilerplate
Notes
- If the input story is actually an epic (multiple independent capabilities), recommend splitting it and generate criteria for the first sliceable story rather than producing shallow criteria across all of them.
- The most common failure mode in acceptance criteria is missing negative cases — for every rule that permits something, there should be a scenario for what happens when it's violated.
- Given/When/Then criteria map cleanly to automated tests (Cucumber, SpecFlow, Behave); writing them well upfront pays off directly in test coverage.
- When non-functional requirements are unstated, don't invent thresholds — list them as open questions so the team commits to real, testable numbers.
How to use this skill
This file is a Claude Code skill in Anthropic's standard format — markdown with YAML frontmatter at the top.
Installing in Claude Code:
~/.claude/skills/<folder-name>/SKILL.md— auto-loads in every session anywhere on your machine (recommended for skills you'll use across multiple projects)<your-project>/.claude/skills/<folder-name>/SKILL.md— auto-loads only when working in that project (recommended for project-specific skills)
Restart Claude Code or open a new session to register.
Using in Claude.ai, ChatGPT, Gemini, or other AI tools:
- Drag this file into a new chat, or copy and paste its contents
- Send your task or request as your next message — the AI will apply the skill where it fits
For Claude Code skill details: https://docs.anthropic.com/en/docs/claude-code/skills