Use when writing a new requirement, defining a new feature, or when asked to implement behavior that has no requirement in specs/. Produces an EARS requirement with an FDD-style feature name, anchor Gherkin scenarios, and a stable REQ ID. Also use when an existing requirement must change.
90%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
One requirement = one file in specs/, named after its ID: specs/REQ-SALE-003.md.
Use the template at templates/requirement.md.
Format: REQ-<AREA>-<NNN>.
<AREA>: short uppercase domain area (SALE, AUTH, SCRAPE...). Reuse existing
areas: ls specs/ | cut -d- -f2 | sort -u. Invent a new one only for a
genuinely new bounded context.<NNN>: next free number in that area: ls specs/REQ-<AREA>-*.superseded and a pointer.<action> the <result> <by|of|for|to> a(n) <object>
Examples: "Calculate the total of a sale", "Reject the login of a locked
account". This is the vocabulary lock: the nouns and verbs here are the only
ones to use in code, tests, and conversation for this feature. Do not invent
synonyms later (no applyRebate when the spec says discount).
If the feature can't be named in this form in one line, it is too big — split it.
Three questions to ask of every requirement before accepting its shape:
These heuristics are LEGAL at spec level and ILLEGAL at code level. Deciding to spec the general problem is design; writing generalized code no test demands is a Three Laws violation (tdd-cycle, Law 3). Generalize the requirement, then let the tests force the generality into the code.
Also: the <AREA> prefix is a business capability and should match the
module directory (screaming architecture — REQ-PRICING-* ↔ src/pricing/).
If you can't pick the AREA, you haven't found the bounded context yet;
that's a design conversation with the human, not a naming problem.
Pick the matching template. One requirement statement per file.
| Pattern | Form |
|---|---|
| Ubiquitous | The system shall <response> |
| Event-driven | When <trigger>, the system shall <response> |
| State-driven | While <state>, the system shall <response> |
| Unwanted behavior | If <condition>, then the system shall <response> |
| Optional feature | Where <feature is present>, the system shall <response> |
The EARS statement is universally quantified — it is the law. Be precise about units, ranges, and boundary inclusivity ("0–100 % inclusive", not "a valid percentage").
1–3 scenarios maximum. They are conversation artifacts and canonical examples, not exhaustive test scripts — properties and the type system carry exhaustiveness.
Two supported spec modes — pick per project, record the choice in an ADR:
Mode A — markdown anchors (default for greenfield): scenarios embedded
in this spec file, translated by hand into plain #[test] functions.
Lightweight; the scenario is a conversation artifact.
Mode B — executable .feature files (default for ports/parity projects,
or whenever spec↔test drift is the dominant risk): scenarios live in
features/ as real Gherkin run by cucumber-rs; the spec file links to them
instead of embedding. The .feature IS the test — spec↔test drift becomes
mechanically impossible, which matters most with agents, who are precisely
the authors that let markdown specs and test code diverge. Side benefit:
fn-hash hashes each Scenario block, so scenario-level change detection
works on the spec itself. Cost: you own a step-definitions layer — keep
steps thin (parse, call the port, assert); business logic in step defs is
Zone-1 leakage. In Mode B the slice WIP convention uses a
@wip(REQ-<AREA>-<NNN>) tag excluded from the default cucumber run instead
of #[ignore] — same rules, same staleness audit.
When a reference implementation exists, it — not your intuition — is the
spec source. Before writing any requirement or scenario for behavior being
ported: READ the corresponding source in the reference implementation. Do
not guess what the original does; do not infer it from its output alone.
The EARS statement describes the original's observable behavior; the spec
file records WHERE in the reference it lives — file + function/sub name
+ line range — so the next session can re-check the oracle instead of
trusting your reading. Name the reference function in the commit subject
too (search: grep tree content (git_search_files)): commit ↔ reference
traceability for free.
Deliberate divergences from the reference (modernized markup, dropped
misfeatures) are not silent: each one is named in the spec under
## Divergences, with the reason — otherwise a future conformance test
failure is undiagnosable as bug-vs-decision.
Field-proven additions to the mode:
Rules:
Scenario Outline with an Examples: table instead of prose scenarios.
The table IS the spec.Before finishing, list 1–3 candidate properties (invariants, round-trips,
identities) implied by the requirement, in plain language, under
## Candidate laws in the spec file. The verification-ratchet skill turns
these into property tests. If you cannot state a single law, the requirement
is probably an example in disguise — reconsider its EARS form.
rg 'REQ-<ID>' --type rust specs/ src/ tests/ — list every artifact bound to it.revision: field in the spec front-matter and add one line to
its ## History.ls specs/REQ-<AREA>-<NNN>* returns only this file.igouss/gitweb-rs
9ef2429
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.