AGENT SKILL

plan-writing-gherkin-criteria

Guides writing Given/When/Then acceptance scenarios that describe observable behaviour and can actually fail.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 2
Forks
0

01 前言 Front Matter

name
plan-writing-gherkin-criteria
description
Guides writing Given/When/Then acceptance scenarios that describe observable behaviour and can actually fail.
when_to_use
Use when authoring or reviewing the acceptance criteria section of a plan's product requirements.
compatibility
Requires no tools beyond the plan being written.

03 SKILL.md 正文

Writing Gherkin Criteria

A scenario states a condition that could fail. That is the whole test of a good one.

The Three Clauses Do Different Work

  • Given — the state before, and only what matters. Setup that no clause depends on is noise, and noise is where wrong assumptions hide.
  • When — one action. Two actions means two scenarios, or a scenario that cannot say which action caused the result.
  • Then — one observable outcome. Observable means someone or something outside the system can see it.

Observable, Not Internal

Then the cache is warmed describes an implementation. It will be marked complete by whoever wrote the cache, and it will keep passing after the cache is removed.

Then the second request returns without contacting the upstream service describes behaviour. It survives the rewrite, and it fails when the behaviour goes away — which is the only thing it was for.

Falsifiability Is the Filter

Ask: what would this look like if it were false? A scenario with no answer is not an acceptance criterion. It is a statement of intent that has been formatted like one.

Then the interface is intuitive has no failing case. Then a first-time user completes checkout without opening help does.

One Scenario, One Claim

A scenario asserting several things fails as a unit and reports nothing about which part broke. Splitting costs a few lines and buys a diagnosis.

Stable Identifiers

Each scenario carries an identifier that does not change when the text is edited or the list is reordered. Delivery items cite it, reviews record against it, and other implementations match on it.

Renumbering scenarios silently breaks every reference to them, and nothing reports the break — the citations still parse, they just point somewhere else now.

Write Them Before the Technical Shape

Criteria written after the design describe the design. Written before, they constrain it, which is the entire reason to write them down rather than assume them.

04 同仓库更多 Skills

wahidyankf
wahidyankf/beaver-nest

writing-browser-e2e-tests

Guides writing browser end-to-end tests that find elements as users do, wait on what the action produced, keep page knowledge in page objects, organize one feature per file, and run scenario-backed suites from generated specs.

★ 2
wahidyankf
wahidyankf/beaver-nest

usability-heuristic-evaluation

Guides judging a running interface as a first-time user would, without its specifications: citing a named principle for every finding, walking each task step, reading labels and addresses for scent, and rating severity.

★ 2
wahidyankf
wahidyankf/beaver-nest

tooling-nx

Guides Nx workspace work under the Nx standard: selecting projects by the graph, adding a target only where a capability exists, tracing a stale cached pass to its missing input, and answering a module-boundary finding.

★ 2
wahidyankf
wahidyankf/beaver-nest

programming-typescript

Guides the procedure for writing or changing TypeScript: loading the TypeScript standard first, driving each increment test-first, finding which rule a decision falls under, and confirming the gates before handing off.

★ 2
wahidyankf
wahidyankf/beaver-nest

programming-shell

Guides shell work under the shell standards: checking the declared dialect first, deciding whether logic belongs in shell at all, tracing where exit-on-error does not reach, and testing the script as its callers run it.

★ 2
wahidyankf
wahidyankf/beaver-nest

programming-javascript

Guides JavaScript work under the JavaScript standard: confirming the file is type-checked, typing through JSDoc, validating input the checker cannot see, and noticing floating promises and swallowed errors before handing off.

★ 2