From qa-lead
Write acceptance criteria for a user story using Example Mapping and Given/When/Then format. The primary output of the 3 amigos session (product + dev + QA). Use when a story needs testable criteria before development starts.
npx claudepluginhub hpsgd/turtlestack --plugin qa-leadThis skill is limited to using the following tools:
Write acceptance criteria for $ARGUMENTS.
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Designs, implements, and audits WCAG 2.2 AA accessible UIs for Web (ARIA/HTML5), iOS (SwiftUI traits), and Android (Compose semantics). Audits code for compliance gaps.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Write acceptance criteria for $ARGUMENTS.
Acceptance criteria define the boundary of "done" for a story. They must be testable, unambiguous, and written in business language. Every criterion is a contract between product, development, and QA.
Before writing criteria, decompose the story:
Search the codebase for related features, existing test files, and prior acceptance criteria to understand patterns and avoid contradictions.
Business rules are the constraints that govern the story's behaviour. Each rule becomes a group of scenarios.
Use Example Mapping to structure the discovery:
| Colour | Represents | Examples |
|---|---|---|
| Yellow | The story | "As a billing admin, I want to apply a discount code" |
| Blue | Business rules | "Discount codes can only be used once per account" |
| Green | Examples per rule | "Given a valid code, When applied, Then the discount is reflected in the total" |
| Red | Questions / unknowns | "What happens if the code expired 1 minute ago mid-checkout?" |
List every business rule before writing scenarios. Common sources of rules:
Rule: If you discover a red card (unanswered question), flag it explicitly. Do not invent an answer. Unresolved questions block development.
For each business rule, write concrete scenarios using Gherkin syntax:
Rule: [Business rule in plain language]
Scenario: [Happy path — the expected behaviour]
Given [precondition — system state, user state, data state]
And [additional precondition if needed]
When [action the user takes]
And [additional action if needed]
Then [observable outcome]
And [additional outcome if needed]
Scenario: [Error case — what happens when something goes wrong]
Given [precondition]
When [action that triggers the error]
Then [error behaviour — what the user sees, what the system does]
Scenario: [Edge case — boundary conditions]
Given [precondition at the boundary]
When [action]
Then [expected behaviour at the boundary]
Every business rule must have at minimum:
| Scenario type | Purpose | Required |
|---|---|---|
| Happy path | The expected, successful flow | Yes — always |
| Validation error | Invalid input is rejected correctly | Yes — if the rule involves input |
| Permission denied | Unauthorised user is blocked correctly | Yes — if the rule involves permissions |
| Edge case | Boundary values, empty states, maximums | Yes — always |
| Concurrency | Simultaneous actions handled correctly | If applicable |
Rules for writing scenarios:
Then clauses testing different behaviours, split the scenario.Functional criteria say what the system does. Non-functional criteria say how well it does it.
| Category | Criterion | Threshold | How to test |
|---|---|---|---|
| Performance | Page load / API response time | < 2s page / < 500ms API at p95 | k6 load test, integration timing |
| Accessibility | Keyboard + screen reader | Full flow without mouse, elements announced | Playwright keyboard + axe-core |
| Security | Auth enforced, input sanitised | 403 for unauthorised, no XSS | Role-based integration tests, security suite |
| Resilience | Graceful degradation | Error state when dependency is down | Integration test with dependency unavailable |
Include only the categories relevant to this story.
Each criterion must be mapped to a test level so QA and development know where it gets verified:
| Criterion | Test level | Rationale |
|---|---|---|
| [Business rule scenario 1] | Unit | Pure logic, no dependencies |
| [Business rule scenario 2] | Integration | Involves database/API boundary |
| [Permission check scenario] | Integration | Requires auth middleware |
| [Happy path end-to-end] | E2E | Critical user flow |
| [Performance criterion] | Performance | Requires load testing tool |
| [Accessibility criterion] | Manual + automated | axe-core catches 30-50%, rest needs manual review |
Rules for test level assignment:
Run these final checks before declaring the criteria complete:
| Property | Check | Status |
|---|---|---|
| Independent | Can this story be delivered without other stories in progress? | [Yes / No — dependency] |
| Negotiable | Are the criteria flexible on implementation while fixed on outcome? | [Yes / No — over-specified] |
| Valuable | Does completing this deliver user or business value? | [Yes / No — missing value] |
| Estimable | Can the team estimate effort from these criteria? | [Yes / No — unclear] |
| Small | Can this be completed in a single sprint? | [Yes / No — split suggestion] |
| Testable | Can every criterion be verified pass/fail? | [Yes / No — vague criterion] |
Verify you have covered: empty/null input, maximum/minimum values, special characters, concurrent access, network failure, permission boundaries, and time zone variations (if applicable).
Explicitly list what this story does NOT cover to prevent scope creep.
# Acceptance Criteria: [Story title]
**Story:** As a [user type], I want to [goal], so that [value]
**Scope:** [what's in] | **Out of scope:** [what's out]
## Business Rules and Scenarios
### Rule 1: [Business rule]
**Scenario: [Happy path]**
- Given [precondition]
- When [action]
- Then [outcome]
**Scenario: [Error case]**
- Given [precondition]
- When [action]
- Then [outcome]
**Scenario: [Edge case]**
- Given [precondition]
- When [action]
- Then [outcome]
### Rule 2: [Business rule]
[scenarios...]
## Non-Functional Criteria
| Category | Criterion | Threshold |
|---|---|---|
| [category] | [criterion] | [threshold] |
## Test Level Mapping
| Criterion | Level | Notes |
|---|---|---|
| [criterion] | [unit/integration/e2e] | [rationale] |
## Open Questions
| Question | Impact | Owner |
|---|---|---|
| [unresolved question] | [blocks/informs what] | [who resolves] |
/qa-lead:test-strategy — provides the overall test strategy context (tools, levels, coverage targets) that acceptance criteria map into./qa-engineer:generate-tests — consumes acceptance criteria to generate executable test code. Write the criteria first, then generate the tests./product-owner:write-user-story — produces the user stories that acceptance criteria are written for. The story defines what; the criteria define done.