writing-acceptance-criteria
Skill0 starsChanged 3 months agoApache-2.0View on GitHub
Write or assess acceptance criteria that are binary, observable, and testable. Use when refining a story, running the G1 Definition of Ready gate, reviewing whether criteria are testable, converting a vague requirement into something QA can prove, or writing non-functional requirements with concrete thresholds.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- bostonaholic/skillstheir own version, first seen Nov 16, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- bostonaholic/skills★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository18 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ai-impact-assessmentSkill
- artifact-intakeSkill
- backlog-prioritizationSkill
- blameless-postmortemSkill
- control-assessmentSkill
- control-verificationSkill
- dependency-vettingSkill
- eval-designSkill
- evidence-writingSkill
- exploratory-testingSkill
- red-teamingSkill
- retro-facilitationSkill
- scanner-triageSkill
- secure-code-reviewSkill
- story-splittingSkill
- test-strategySkill
- threat-modelingSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
If yes, it is not a criterion.
- Distinctive: line 80
"Fast" and "secure" are not criteria: If you cannot state the number, that is a spike — not a guess written down.
- Distinctive: line 105
Write open questions down explicitly.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Writing acceptance criteria
Consumers: product-owner, /refine, /ready, process/gates/g1-ready.md, qa-engineer
(traceability).
The single test
Could a reasonable person argue this passed when it did not?
If yes, it is not a criterion. This one question decides most G1 rejections and is worth applying to every line before anything else.
Form
Given/When/Then. Cover three cases, minimum:
# happy path
Given I am editing a document and have unsaved changes
When my session expires and I sign in again within 24 hours
Then I am offered my most recent draft with its edit timestamp
# error path
Given my draft exceeds the 5 MB per-user storage limit
When autosave runs
Then the save is rejected, the oldest draft is evicted, and I see a non-blocking notice
# boundary
Given I have exactly 5 stored drafts and the limit is 5
When I create a sixth
Then the oldest is discarded and the new one is storedThe error path and the boundary are where the defects are. A story with only happy-path criteria has not been refined; it has been described.
Failure patterns
| Written | Why it fails | Rewrite |
| "The user sees their draft" | Which draft? Sees it where? In what state? | "The most recent draft is offered with its edit timestamp" |
| "The page loads quickly" | Unfalsifiable | "p95 < 200 ms at 100 concurrent users" |
| "The UI is intuitive" | Not observable | Delete it. If it matters, it is a usability test with a task success rate |
| "Errors are handled gracefully" | Which errors? What is graceful? | "On upstream timeout, the editor stays open, retries twice, then shows a retry action" |
| "Data is stored securely" | Restates the wish | "Draft bodies are encrypted at rest; a non-owner receives 403 on read" |
| "Works on mobile" | Which devices, which behaviour? | "At 375 px width the toolbar collapses and all actions remain reachable" |
| "Should validate input" | No boundary, no behaviour | "Titles over 200 chars are rejected with a field-level message; the draft is not saved" |
The implementation-spec trap
Criteria state the need, not the solution — otherwise the story stops being negotiable (the N in INVEST) and the team loses the freedom to find a cheaper answer.
✗ "A `drafts` table is created with columns id, user_id, body, updated_at"
✓ "A draft survives a browser crash and is offered on next sign-in"The first forecloses the design at refinement time, by someone not building it.
Non-functional criteria — with numbers
These are criteria, not decoration, and they carry the same binary test. Attach the ones that apply:
| Type | Shape | Example |
| Performance | threshold + load + data volume | "p95 < 200 ms at 100 concurrent users with 10k drafts" |
| Security | the authz rule, the validation boundary, the audit event | "Only the owner may read a draft; audit.draft.restored is emitted with actor and draft id" |
| Privacy | what data, retention, minimization | "Draft bodies are deleted 30 days after account closure" |
| Accessibility | standard + interaction | "WCAG 2.2 AA; fully operable by keyboard; state changes announced" |
| Observability | what must be emitted to debug it | "Emits draft.restore.failed with reason code" |
| Reliability | the failure mode and the degradation | "If the store is unavailable, editing continues locally and the user is told saving is paused" |
"Fast" and "secure" are not criteria. If you cannot state the number, that is a spike — not a guess written down.
Relevance triage
While writing criteria, flag the story per docs/10-definitions.md. Any flag makes G2
mandatory, and getting this wrong at refinement is what produces an expensive surprise at
G4.
- Security-relevant — authn, authz, sessions, crypto, secrets, personal/regulated data, file upload or parsing, external calls, deserialization, template rendering, subprocess, query construction, infra/CI config, or a new dependency.
- AI-relevant — model call, prompt, system instruction, generation parameter, retrieval/grounding data, tool-calling capability, autonomy boundary; user data through a model; model output into a user-affecting decision.
- Privacy-relevant — collects, processes, stores, transmits, or deletes personal data, or changes retention, access, or purpose.
When uncertain, flag it. An unnecessary G2 costs an hour; a missed one costs a release.
The open-question rule
A story with an open question whose answer would change the design is not Ready, however complete its criteria look. Starting anyway means building the wrong thing efficiently.
Write open questions down explicitly. An unrecorded question does not stop existing; it just surfaces mid-sprint as a clarification request, which is the thing refinement exists to prevent.
Handing off to QA
Each criterion should map to one test. If QA cannot see how to prove a criterion true or false, it fails the T in INVEST — fix it now, not at G4.
For every security criterion, expect a negative-case test (proving denial), not just a positive one. Write the criterion so that test is obvious:
Given I am not the owner of a draft
When I request it by id
Then I receive 403 and no draft contentControls
SA-3 · SA-4(3) · SA-8 (security requirements defined at design-in) · SA-11 (testability) · PL-8 · AI RMF MAP 2.3.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

