| name | specification-writing |
| description | Core reference for EARS requirement patterns, Given/When/Then acceptance criteria, RFC 2119 language, requirement ID conventions, and specification quality checklists. Background knowledge for the spec-writer agent. Preloaded by spec-writer via the skills frontmatter field; not user-invocable. |
| user-invocable | false |
Specification Writing — Core Reference
This skill is preloaded by the refinery:spec-writer agent via its skills: frontmatter field. Its content becomes part of spec-writer's system context at agent startup. This skill is not user-invocable — it has no behavior on its own; it is reference material consulted by the agent during synthesis.
The same content (in a slightly different rendering for mode/stage files) lives in ${CLAUDE_SKILL_DIR}/../refine/references/requirement-syntax.md. The two files MUST stay in sync (per NFR-M-001 single-source-of-truth discipline). When updating one, update the other.
1. EARS — Easy Approach to Requirements Syntax
EARS provides six patterns for unambiguous functional requirements. Every functional requirement (FR-NNN) MUST use one of the six patterns.
1.1 Ubiquitous (always active)
The <system> shall <required behavior>.
When to use: a behavior that holds at all times.
Example: "The system shall maintain audit logs for all administrative actions."
1.2 Event-Driven (responds to a trigger)
When <trigger>, the <system> shall <required behavior>.
When to use: a behavior that responds to a discrete event.
Example: "When a user submits a login form, the system shall validate the credentials within 200ms."
1.3 State-Driven (active during a state)
While <state>, the <system> shall <required behavior>.
When to use: a behavior that holds during a specific operational state.
Example: "While the database is in maintenance mode, the system shall reject all write requests with HTTP 503."
1.4 Unwanted Behavior (defensive)
If <unwanted condition>, then the <system> shall <required behavior>.
When to use: a behavior that handles error or exceptional conditions.
Example: "If the upstream API returns a 5xx response, then the system shall retry up to three times with exponential backoff."
1.5 Optional Feature (conditional capability)
Where <feature is included>, the <system> shall <required behavior>.
When to use: a behavior that exists only when a feature is enabled.
Example: "Where the multi-tenant feature is enabled, the system shall scope all queries by tenant_id."
1.6 Complex (multiple triggers)
When <trigger1> and while <state> and if <condition>, the <system> shall <behavior>.
When to use: a behavior with compound preconditions. Use sparingly — prefer decomposition into multiple atomic requirements when possible.
Example: "When a payment is submitted and while the merchant account is verified and if the amount exceeds the daily limit, the system shall require additional authentication."
1.7 EARS anti-patterns (avoid)
| Anti-pattern | Why it fails | Fix |
|---|
| "The system should…" | "Should" = preference, not requirement | Use "shall" for mandatory; "may" for optional |
| "The system handles X" | Not testable | Specify the observable behavior: "logs", "rejects", "retries", "returns" |
| Compound: "validate AND store AND notify…" | Three requirements masquerading as one | Split into atomic FRs |
| "The system shall be fast" | Unmeasurable | Specify the threshold: "within 200ms p95" |
| "The system shall support many users" | Unmeasurable | Specify the scale: "shall support 10,000 concurrent users" |
2. Given/When/Then (Gherkin) — Acceptance Criteria
Every functional requirement (FR-NNN) MUST have at least one acceptance criterion (AC-FR-NNN-N) in Given/When/Then format.
2.1 Structure
Given <precondition>
And <additional precondition> # optional
When <action>
Then <observable outcome>
And <additional outcome> # optional
2.2 Rules
- Atomic: one clear action per scenario; multiple
Whens = multiple scenarios
- Deterministic: same Given+When → same Then
- Observable: testable from outside the system
- Concrete: specific values, not vague qualifiers
- Independent: each AC stands alone
2.3 Example
Given a user with role "admin" and a valid session token
When the user submits POST /api/users with valid payload
Then the response status is 201
And the response body contains the new user's id
And the new user appears in GET /api/users within 1 second
2.4 Edge case patterns
For every primary AC ("happy path"), consider:
- Negative case: preconditions fail
- Boundary case: edge of valid input ranges
- Concurrent case: races between operations
- Error case: upstream failures
3. RFC 2119 (System-Level Specs)
System-level spec artifacts (scope: system) use RFC 2119 keywords. Feature-level specs use EARS exclusively.
| Keyword | Meaning |
|---|
| MUST / SHALL / REQUIRED | Absolute requirement |
| MUST NOT / SHALL NOT | Absolute prohibition |
| SHOULD / RECOMMENDED | Strong recommendation |
| SHOULD NOT | Strong recommendation against |
| MAY / OPTIONAL | Truly optional |
Use uppercase for RFC 2119 keywords. Use lowercase shall inside EARS patterns.
4. Numbering Conventions
| Type | Format | Notes |
|---|
| Functional Requirement | FR-NNN | Per artifact, never reused |
| Non-Functional Requirement | NFR-<CAT>-NNN (categories: P, S, SC, R, A, U, M, C) | Per artifact |
| Acceptance Criterion | AC-<REQ-ID>-N | Per parent requirement |
| Invariant | INV-NNN | Per artifact |
| Resolved Design Decision | RD-NNN | Per artifact |
| Risk | R-NNN | Per artifact |
| Failure Mode | FM-NNN | Per design artifact |
| Principle | P-NNN | Per principles artifact |
| Open Question | OQ-NNN | Per artifact |
| Source Document | SD-NNN | Per source list |
| Ticket | T-NN | Per tickets artifact |
5. Quality Checklist (pre-finalize)
Before any artifact transitions to finalized:
6. Confidence Discipline
| Tier | Required evidence |
|---|
| High | file:line citations OR upstream artifact reference OR user-decision Changelog entry |
| Medium | file:line with "single example" note OR upstream reference with "inferred from" note |
| Low | Item must appear in Open Questions; no evidence required |
The artifact's convergence.high_confidence_ratio = high_count / (high_count + medium_count + open_questions_count).
7. Document Format Compliance
Every artifact written by the spec-writer agent MUST conform to:
- Universal frontmatter per
references/document-format.md §1
- Universal sections (Open Questions, Iteration Log, Changelog) per §2
- Per-artifact body sections per §3 / template
- Tracked claim format per §4
- Numbering conventions per §5
- Confidence tiers per §6
- Status compatibility per §7
When generating an artifact, fill the corresponding template; do not deviate from required sections.
