coder-xieshijie/dev-skills / skills/core-spec
core-spec
VerifiedConverges a conversation and its materials into spec.md, the core decisions; when delivery will be automated, also writes verify.md, the acceptance requirements. Use after discussion and clarification are finished, including when the user confirms core-grill's decision summary.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 28.4 KB |
| agents/openai.yaml | config | 154 B |
| references/cross-model.md | markdown | 6.6 KB |
| references/gap-check.md | markdown | 7.2 KB |
| references/spec-example.md | markdown | 8.9 KB |
| references/verify-example.md | markdown | 10.8 KB |
| references/verify.md | markdown | 18.2 KB |
| scripts/clauses.mjs | script | 5.1 KB |
| scripts/clauses.test.mjs | script | 3.2 KB |
| scripts/freeze.mjsexecutable | script | 4.2 KB |
references/verify.md
View on GitHub# How to write verify.md
Step 6 of core-spec writes verify.md by this document. Deliver one self-contained Markdown file, "<topic>: Acceptance Requirements", in the same language as spec.md, with the default file name `verify.md`. From it, the reader judges what it takes for an implementation to satisfy the spec: where to operate, what results to observe, and what evidence to leave before declaring it done.
This document is finished before the plan and the code are written, from the basis set out in section 1, so omissions in the plan and the implementation do not narrow the acceptance scope. The unit of acceptance is a complete operation whose result the user can observe. During development, the implementing agent drives the real application itself, and a scenario passes only when it actually runs through. verify.md states what to verify and how to judge it; how to start and drive the application belongs to the project's own verification capabilities (control commands, feature map, test tools), which verify.md references. Implementation steps, unit tests and execution results are not part of it.
## 1. List the spec's normative content
Read the whole spec and record its path, the sha256 of its content, and the current commit of each related repository; when the spec is updated later, record the hash again. The spec is the only source of requirements. The current session, ADRs and the glossary help you understand the spec's wording and find concrete examples; requirements come only from the spec.
List the spec's normative content item by item: chosen behaviors, defaults, conditions and exceptions, things that must not happen, existing behavior that must be preserved, non-goals, accepted costs, and invariants. Existing behavior that the non-goals touch goes into the regression scope. Do not list sentences that only explain reasons.
Done criteria: every item of the spec's normative content has a place: it becomes a requirement, or it is merged into another requirement with a note saying so.
## 2. Write agreements as requirements that can be judged
Give each requirement a stable ID (R01, R02, ...), write it as an observable conclusion, and note its location in the spec, down to the specific clause (a list item or sentence within a section): a section that already has other requirements does not mean every provision in that section has a place. When one agreement carries several conditions or exceptions, split it so that each exception can be judged on its own.
Choose a proof method for each requirement:
| Proof method | What it fits |
|---|---|
| Scenario | Behavior, state, output, side effects; run from the real entry point |
| Mechanical check | Structural constraints, e.g. layering direction, reusing a specified capability, no new dependencies, interfaces staying compatible; write them as lint rules or structural tests, one rule per constraint. Where a constraint truly cannot be mechanized, state what review checks and what counts as a failure |
| Existing check | What the repository's existing end-to-end tests, structural tests or lint can already prove; name the specific file or command |
| Test | That an entry point without logic of its own shows what the main entry point shows (see "One full scenario per behavior" below): a component or integration test written in delivery; state what it asserts, in terms the user can observe, and where it runs |
Done criteria: every requirement has a proof method, and the reader does not need to guess how it is judged.
## 3. Design scenarios for behavioral requirements
A scenario is one complete operation a user performs at one entry point, with its result, written as "the user does something at some entry point and sees or produces some result". By default it is driven from the real entry point. Write it with these fields:
```text
S01 <title> Covers: R01, R03
Entry point: the user entry point this scenario drives (a feature map entry or a specific entry point)
Preconditions: the initial state, arranged with test data, configuration or fixtures
Steps: what the user does at the entry point, in order
Checkpoints: one per result; the literal expected value or state taken from the spec, and where it is read from
Must not appear:
Baseline expectation: on the code before the change, fails / passes / the baseline lacks this feature
Decoy implementation: same as baseline / for a key risk the baseline does not cover: a plausible approach that makes this scenario fail
Test double: none / which external dependency uses a test double, and at which integration layer
Evidence:
Execution status: entry point exists / needs verification capability (see tooling gaps) / bind command after implementation
```
**Splitting and merging.** Split when results differ: every provision of the spec, every exception, and every state that leads to a different result must be covered by a scenario, and every entry point the change touches is covered as the next paragraph but one says. What has the same entry point and the same preconditions and can be checked one after another in one operation flow goes into one scenario, with one checkpoint per result; what needs a different entry point or different preconditions goes into separate scenarios. Split by results the user can observe; implementation steps and internal functions are not grounds for splitting.
**Choose the form of proof by type of change.**
| Change | Form of proof |
|---|---|
| CLI | Run the real command; check the output and exit code |
| UI | Walk the changed flow in the running app |
| Storage | After writing, read the value back from a separate read-only view |
| Parsing or migration | Replay saved real inputs |
| Platform support | Run on the target platform the spec names |
| Performance (when the spec requires it) | In the same environment, measure the baseline first, then the change; state the metric and the value that counts as failure |
**Make internal rules observable first.** For internal rules that cannot be seen from the entry point, such as counts, the parameters actually sent, or the data written, first add observability (logs, metrics, traces or a read-only query) and list it as a verification tooling gap; the scenario still starts from the entry point. Trigger conditions such as failures or rate limiting of external dependencies with a test double placed in the layer that connects to the external system; a test double proves only the behavior inside its boundary. When the spec requires a real provider, a real device or the target platform, the scenario runs in the real environment. Unit tests of how the code works inside belong to the implementation and do not go into verify.md.
**Take the real user path.** Preconditions may be arranged with test data, configuration, permissions or supported test flags; the behavior under verification must come from real operations at the entry point. Internal setters, test-only interfaces and direct writes to storage are used only to arrange preconditions.
**Observe the actual result.** Evidence directly proves the result the spec requires. When the requirement is itself about what is displayed, the UI is direct evidence. When the requirement involves the parameters actually sent, the persisted state, the wiring under default startup or other side effects, observe both the action and the state change it causes, and read back the actual value or state; do not infer it from a UI message, a function being called or a log line.
**Assertions must be able to fail.** Checkpoints use the literal values the spec gives, not values computed by the code under test. Pair each "must not appear" item with a positive checkpoint in the same scenario, which proves the flow actually ran. The check: would the scenario still pass if the implementation did nothing or returned empty? If it would, rewrite the checkpoints. For a feature whose interaction the spec specifies, a display-only stub that cannot be interacted with must also fail, so these checkpoints assert the effect the interaction produces, not just that the control appears.
**Compare against the baseline.** For new or changed behavior, the scenario should fail on the code before the change; for behavior that must be preserved, it should pass both before and after the change. When the baseline lacks the feature, say so, and judge the added behavior and the end state the user waits for instead. The baseline is the first ready-made decoy implementation. For a key risk it does not cover, write one more plausible decoy implementation and confirm that the checkpoints make it fail.
**One full scenario per behavior, at its main entry point.** When the same behavior can be triggered from several user entry points, write its full scenario, with every checkpoint, at the main entry point: the one most users use, or whose path covers the most of the change. Another entry point gets a full scenario of its own only when it has logic of its own for this behavior beyond showing what it receives: its own state, timing or input handling, or its own path into the code that implements the behavior. Every other entry point the change touches gets a wiring scenario that walks the new behavior there once and checks that it is wired up and that its key result shows; one wiring scenario may cover several behaviors at its entry point, and an entry point a full scenario of this change already drives needs none. That the other entry points show the same results as the main one is a requirement proven by component or integration tests, named in the requirements table. Each scenario becomes a script that runs at its milestone and again in every verification round, so spend scenarios on what tests cannot see at an entry point: whether it is wired up, logic of its own, and what shows only in its real interface.
**Constrain only what the spec specifies.** Checkpoints check the results the spec requires. Internal structure, naming and implementation paths that the spec does not specify are left to the implementation; other correct implementations should be able to pass.
**Results that code cannot assert**, such as model output quality or visual effects: state the fixed samples, the reference and the judging criteria, and note that independent judgment is needed.
Done criteria: every provision, exception and result-changing state in the spec is covered by a scenario, and every entry point the change touches has a full or a wiring scenario as above; every scenario has literal checkpoints and a baseline expectation, and where the baseline does not cover a key risk, it also has a decoy implementation; no two scenarios have exactly the same entry point, preconditions and operation flow.
## 4. Locate verification capabilities; list tooling gaps and coverage blind spots
First find the project's existing verification capabilities: verification Skills, control commands, feature map, end-to-end test tools, existing tests, logs, metrics and data queries. When there is a feature map, a scenario's "Entry point" references its feature map entry and drive commands; do not rewrite the drive steps in verify.md. A referenced entry point must exist in the recorded commit; what you cannot confirm from the repository is marked "bind command after implementation" or listed as a verification tooling gap. Whether it actually runs is verified in the delivery stage.
For features implemented in this change, state the type of entry point and how the result is observed; bind the specific commands at acceptance after implementation. Mark commands, parameters and paths not yet determined as "bind command after implementation".
What cannot be observed or driven now goes under "Verification tooling gaps": what is missing and which scenarios it serves. During delivery, prefer reusing the project's existing verification capabilities, fill only the minimal gaps these scenarios need, and keep them as reusable entry points according to the repository's rules, for example an extra observation in a control command, a read-only query or metric, or an entry in the feature map.
Parts that existing tools cannot see or operate, and that this change does not fill (for example, the driving tool cannot see browser-native dialogs), go under "Coverage blind spots": write each blind spot as one list item or table row, stating the affected scenario IDs and checkpoints and which test or check is used to judge them instead; when the test does not exist yet, write what it must assert and in what environment it runs (for example, a real process or an in-process simulation). During delivery, the test is written as this item says, and independent verification judges by this item. The independent verifier recognizes only the blind spots in these items; IDs mentioned in passing in a paragraph do not count. Checkpoints inside a blind spot cannot be marked verified.
Check also that each scenario's preconditions can be produced in the current product through the entry points it names, not only that the entry points exist: read the code on the path. When the product stops a step (a guard, a disabled path, a state it never enters, such as a subagent that cannot start a subagent of its own), rewrite the scenario to reach the same result another way, or list the step as a coverage blind spot with its substitute check, citing the code. Found only in delivery, such a step costs a refreeze and a verification against the old verify that cannot pass.
Done criteria: each scenario's execution status is marked truthfully, each scenario's preconditions can be produced or are listed as blind spots, and each gap and blind spot maps to scenarios.
## 5. Write the document
The document contains, in order:
1. **Purpose and authority**, adjustable to the topic:
> Based on the spec, this document defines what counts as doing this requirement right and how to prove it. It is the shared basis for implementation, independent verification and final acceptance. During implementation, the implementing agent runs these scenarios itself, and a scenario passes only when it actually runs through; after freezing, scenarios and checkpoints do not change, except through the refreezes deliver is authorized to make. This document only describes acceptance requirements; it does not mean verification has been run or has passed.
Then write the sources: the spec path and sha256, the related repositories and commits, and the verification Skill or feature map referenced.
2. **Key points**: the number of requirements, full scenarios and wiring scenarios, and the 3–5 scenarios most likely to go wrong, usually real cross-module paths, default wiring and key exceptions; then the verification depth, as the line `Verification depth: light` or `Verification depth: full` followed by its reason in one sentence (see below); readable within one screen.
3. **Smoke set**: a few core user journeys chosen by the risk of this change, preferring existing features this change touches, to confirm that the environment and existing features are not broken.
4. **Requirements table**: ID, requirement, spec location, proof method.
5. **Scenarios**.
6. **Regression scope**: existing behavior this change touches that the spec does not ask to change, covered by the repository's existing tests or additional scenarios; these scenarios should pass both on the baseline and after the change. A check here that fails the same way on the baseline is a baseline failure, which the verifier proves by running it there and leaves out of the verdict ([verifier brief](../../deliver/references/verifier-brief.md)), with no change to verify. Behavior the spec explicitly changes is not a regression; its old tests are updated with it. Existing scenarios and tests found in step 5 to depend on changed behavior while their purpose stays the same belong here too, run after the change with the adjustments the spec gives.
7. **Verification tooling gaps**.
8. **Coverage blind spots**.
9. **Done criteria**, written as a list, one item each: the smoke set, the regression scope and all scenarios (except checkpoints in coverage blind spots) pass by actually running; checkpoints in blind spots are marked UNVERIFIED and listed separately, and the substitute test or check written for each has been run and passed; the evidence matches the code and running instance of the delivered version; scenarios that lack tools are truthfully marked blocked, not replaced by unit tests or other lower-level checks. When the project has feature maps, add one item: the maps and scenario scripts of every feature whose user-visible behavior or entry points this change alters describe the new behavior, and the maps' structure check passes. When the requirement has other done criteria, add them here. The implementation and the independent verification both judge against this section, item by item.
**Verification depth** sets how many intermediate checks delivery runs; both depths end with the same independent verification by another family against the same done criteria. At `full`, deliver also has another family preview the plan, checks milestones that later work builds on, and has another family review the code before verification. Such checks are worth their cost only where the model does not reliably get the work right on its own, so choose by that:
- `full`: behavior across several features, or in modules other features share (a common runtime loop, a shared package's contract); default startup wiring; a migration, or a contract shared with another repository or service; metering, permissions or security; or a kind of change that has gone wrong in this repository before.
- `light`: a change inside one feature, including one that touches persistence, concurrency or recovery within that feature; or a behavior-preserving change whose touched code existing scenarios and tests already cover. One feature includes its own layers (UI, IPC, its runtime service) and every client that offers the same action.
When the user or the confirmed decision summary names the depth, use it; if the change has a trait above that calls for the other depth, say so in the reason. Otherwise, when in doubt, choose `full`. Write the line in English as shown, whatever the language of verify; deliver reads it.
When deciding split granularity, how tight checkpoints should be, the proof method, or how to write a decoy implementation, read [the example and check cases](verify-example.md).
Deliver one `verify.md` in the location the user specifies; when no separate location is given, put it in the same directory as the spec.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |