write-specs
Spec a feature's observable behavior. Use when asked for requirements, when a request says what the system should do but not how, or to capture what a built system already guarantees. Not for how to build it (write-plan).
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- write-specs
- description
- Spec a feature's observable behavior. Use when asked for requirements, when a request says what the system should do but not how, or to capture what a built system already guarantees. Not for how to build it (write-plan).
03 SKILL.md 正文
Write Specs
A spec fixes what must be observably true; a plan fixes how. A requirement is black-box or it is prose — paths, function names, and libraries belong in the plan.
Steps
1. Ground it
Read the system before describing it — existing code, related specs, whatever fixes the vocabulary. Fan out research where the repo holds the answer; it reads while you write. Resolve what you can from that material; where it is silent, state the default you chose as an assumption. Leave a [NEEDS CLARIFICATION: <question>] marker inline instead only where a wrong guess would invalidate a requirement rather than adjust it. Ask the user only what the material cannot answer — grilling is how.
Done when every claim is traceable on the page: a link to what you read, a quoted user answer, a line in Assumptions, or a marker.
2. Write it
Fill the template. Requirements get stable IDs (R1, R2, …) — the plan references them and test names cite them verbatim (tdd). IDs are never renumbered; new ones append.
Done when every requirement has a stable ID and at least one scenario, every input has a malformed-version requirement, every dependency an outage requirement, every list an empty case, and every reference out of the file is a working relative link.
3. Falsify it
Its own pass over the finished set — contradictions and missing story behavior are only visible across requirements, never inside one.
Per requirement, name the single observation that proves it false, on the page beside its ID; verify-specs runs it once the change lands. If you cannot name one, it is prose — rewrite until a black-box observer could fail it. Then read the set once as a whole.
Done when every requirement carries its falsifying observation, no two requirements contradict (no input or state triggers two requirements whose responses cannot both hold), every story in Users and stories names the requirement IDs that deliver it, and every marker appears in the open-questions list.
Requirement syntax
One obligation per statement — the gate is the falsifier in step 3. The EARS patterns below match a statement to its trigger; shall marks the obligation.
| Pattern | Template | Use for |
|---|---|---|
| Ubiquitous | The <system> shall <response> |
property that always holds |
| State-driven | While <state>, the <system> shall <response> |
holds during a condition |
| Event-driven | When <trigger>, the <system> shall <response> |
response to an event |
| Optional | Where <feature is included>, the <system> shall <response> |
flagged or variant builds |
| Unwanted | If <trigger>, then the <system> shall <response> |
errors, failures, abuse |
| Complex | While <state>, when <trigger>, the <system> shall <response> |
both, when both matter |
Quality claims carry a number and a measurement point — not "fast" but "within 200 ms at p95, measured at the API boundary".
Scenarios use Given/When/Then, one per branch:
- **R4** When a session token has expired, the API shall reject the request.
- Falsified by: a read with an expired token returning anything but 401.
- Given an expired token, When a read is requested, Then the response is 401.
- Given a valid token, When a read is requested, Then the response is 200.
Referencing
A change keeps one directory: docs/plan/YYYY-MM-DD-<name>/, dated the day it is created — by whichever skill creates it first. Every artifact scoped to that change sits in it: <name>.spec.md, <name>.delta.md (spec delta), <name>.spec-hunt.md (spec-hunt), <name>.plan.md, <name>.plan-hunt.md (plan-hunt), <name>.run.md, <name>.verify.md, <name>.hunt.md (bug-hunt), <name>.diagnose.md (diagnose), <name>.refactor.md (refactor), <name>.map.md (frontier), and the QA set <name>.test-plan.md, <name>.cases.md, <name>.regression.md (write-qa).
A record that outlives the change that made it sits outside those directories: decisions at docs/adr/ (write-adr), QA standing records at docs/qa/ (write-qa). Where such a record is numbered, the number is NNN-<slug>, zero-padded, the next one found by scanning its directory.
Links are relative to the file they sit in. Depth from a file to repo source:
| File | Lives in | Repo root is |
|---|---|---|
| spec, plan, run log, verdict, QA | docs/plan/<dir>/ |
../../../ |
| ADR | docs/adr/ |
../../ |
| QA standing record | docs/qa/ |
../../ |
| frontier map | docs/plan/<dir>/ |
../../../ |
| frontier ticket | docs/plan/<dir>/tickets/ |
../../../../ |
related spec [`auth spec`](auth.md)
decision [`ADR-004`](../../../docs/adr/004-tokens.md)
existing code [`db.ts:40-60`](../../../src/lib/db.ts#L40-L60)
requirement [`R2`](auth.md#requirements)
Requirement IDs are cited by label and linked to their section. Terms the spec defines stay in backticks (token_expired) — a reader greps for them.
Template
# Spec: <system or feature name>
<One sentence: what this does for whom.>
## Why
2–5 sentences. For a proposed change: the problem, who hits it, what it costs
today, what is true once this exists. For an existing system: the guarantee,
who depends on it, what a change risks without it. Intent is what lets a
correct judgment call happen later when a requirement turns out to be
underspecified.
## Users and stories
Prioritized, each a slice that could ship and be demonstrated on its own, each
naming the requirement IDs that deliver it:
- **P1** — As a <user>, I want <capability>, so that <outcome>. (R1, R4)
## Requirements
- **R1** The `<system>` shall …
- Falsified by: <the single observation that proves it false>
- Given …, When …, Then …
- **R2** If <bad input>, then the `<system>` shall …
- Falsified by: …
- Given …, When …, Then …
## Constraints
Non-functional bounds. Existing decisions this must stay consistent with,
quoted, each linked to its source ([write-adr](../write-adr/SKILL.md) writes
them): "tokens expire at 24 h — [`ADR-004`](rel-path)".
## Out of scope
What a reader would expect and will not get, one line of why each.
## Success criteria
2–4 measurable, technology-agnostic outcomes — observable without reading the
source.
## Assumptions and open questions
Defaults you chose where the input was silent, stated as choices. Then every
`[NEEDS CLARIFICATION]` marker still in the file, each linked to the
requirement it blocks, with who can answer it.
Spec delta
Amending a spec that already exists is a delta against its current IDs, never an edit in place, so a reader sees exactly what moved. Write it as <name>.delta.md in the directory of the change that makes it — <name> is that change's name, under the referencing convention — with a first line linking the spec it amends: "amends auth spec" when that spec sits in the same directory, "amends auth spec" when an earlier change owns it. One delta per change: a later amendment in the same change adds to it. ADDED and MODIFIED entries each carry their own falsifying observation. verify-specs scores the amended spec with the delta applied, then folds the delta into it once every ID is met, IDs intact.
amends [`auth spec`](auth.spec.md)
## ADDED
- **R9** When … the system shall …
- Falsified by: …
- Given …, When …, Then …
## MODIFIED
- **R3** was: <old text> — now: <new text>. Reason: <one line>.
- Falsified by: <the observation that proves the new text false>
- Given …, When …, Then …
## REMOVED
- **R5** — <why it no longer applies>
When the behavior is settled, hand the spec to spec-hunt — it kills the gaps a cold executor would hit, checked against the Done when lines of the three steps above. A hunt with no Confirmed gap forwards to write-plan, naming each Suspected finding's Settles it check. Confirmed gaps come back here: fix each as a delta, then hand the spec back to spec-hunt.
04 同仓库更多 Skills
unslop
Use when writing or editing prose a person will read, or when text sounds AI-generated.
show-me
Use when asked to show, diagram, or walk through how code fits together or what a change does, or before explaining a multi-file flow in prose.
pr
Use when writing or updating a pull request description, or before running `gh pr create`.
commit
Use when writing a commit message, or before running `git commit`.
write-skills
Write, fix, or audit a skill's frontmatter, trigger description, and body. Use when a skill is asked for, never fires, or fires at the wrong moment. Not for a hook (write-hooks) or the plugin manifest and catalog.
write-qa
Write coverage-mapped QA deliverables. Use when asked for a test plan, manual test cases, a regression suite, or a bug report. Not for automated tests (tdd) or hunting bugs in code (bug-hunt).