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/gap-check.md
View on GitHub# Gap check brief
For the gap checker. In the command, the caller gives the paths and sha256 of spec and verify, the spec's clause list, and the paths of the source agreements and the related repository. The source agreements include the request text, accepted ADRs, and the user's final decisions in their own words together with the questions and options they answered.
## Purpose
After the user confirms these two files, they are frozen; then an agent implements fully automatically and judges whether it got things right only by these two files. Your job is to find, before confirmation, the problems that would make delivery go wrong or impossible to judge. You cannot see the author's reasoning or drafts; this is deliberate: judge only by these two files, the source agreements and the repository.
Read only; do not modify any file. Write the results in your final reply.
When the caller limits the check to the clauses changed since the last round, check those clauses, the clauses next to them and the scenarios that cover them, and state that scope at the start of the report.
## What to check
1. **The spec itself**
- Self-contradiction: two provisions cannot both be satisfied.
- Undecided behavior: how a feature the spec touches behaves at some entry point or in some state (default, loading, empty, error, disabled, cancelled, triggered repeatedly, concurrent, after restart) is not decided, and different reasonable choices would change how some scenario is judged.
- Ambiguity: two reasonable implementations that both match the letter would be judged differently.
- Unadjusted dependents: an existing feature map criterion, scenario script or test in the repository depends on behavior the spec changes (a value it asserts, or a budget, limit, quota or timeout it sets only as headroom), would fail or stop checking what it is for after the change, and neither the spec nor verify's regression scope says how it is adjusted. Report it as a spec missing item.
- Missing items: there is no purpose; the spec is for automated delivery but has no delivery and authorization (which repository and branch to deliver to, whether the agent may push and open an MR); a specific adjacent matter would materially change the delivery scope, yet the spec does not say whether it is done.
2. **spec → verify**: every normative item in the spec (behavior, defaults, conditions and exceptions, things that must not happen, existing behavior that must be kept, non-goals, accepted costs) maps to a requirement and a way to prove it; each behavior has a full scenario at its main entry point, an entry point with logic of its own for the behavior has a full scenario too, and every other entry point the change touches has a wiring scenario ("One full scenario per behavior" in [how to write verify](verify.md)). Compare clause by clause using the clause list, not section by section: a section that already has other requirements does not mean every provision in that section has a place. When one clause contains several provisions, each must have a place. Before reporting missing coverage, check whether an existing test, runtime check or requirement already proves it; report it only when a wrong implementation would otherwise pass.
3. **verify → spec**: there are no requirements, thresholds or semantics beyond the spec.
4. **Discriminating power**: checkpoints take the spec's literal values, not values computed by the code under test; the scenario fails if the implementation does nothing, returns empty, has only the interface without the interactive effect where the spec prescribes interaction, or follows the decoy implementation listed in the scenario; every "must not appear" has a matching positive checkpoint; the baseline expectation agrees with the direction of change in the spec.
5. **Executable**: the entry points, commands and feature map entries a scenario references exist at the repository's current commit, or are marked "bind command after implementation" or listed as tooling gaps; checkpoints the tools cannot see are listed as coverage blind spots. Each step's precondition can be produced in the current product through the entry points the scenario names: read the code on the path, and report a step the product stops (a guard, a disabled path, a state it never enters), citing the code.
6. **Existing facts**: check each existing product fact that spec or verify mentions (keyboard shortcuts, UI text, entry names, defaults, settings) against the repository's current code, and cite where it is; report as an issue anything that does not match the code, and also report anything you could not check.
7. **Source agreements ↔ spec**: every decision, limit, exception and accepted cost the user confirmed in the source agreements has a place in the spec; every normative item in the spec has a basis in the source agreements, and no assistant suggestion has been written as a requirement.
8. **Over-specification**: requirements, scenarios or checks in verify that restate implementation steps, require a document to state process steps the spec leaves to the implementer, prove again what a unit test, a runtime check or another requirement already proves, write a full scenario at an entry point with no logic of its own for the behavior, or need a tool built only for acceptance. Each one is work in delivery and in verification; report it when removing it would not let a wrong implementation pass, and say what to remove or merge.
## What to report
Write the report in the language of spec.md, including the fixed phrases quoted below ("None", "optional", "No issues found"). At the start of the report, state the sha256 of spec and verify that the caller gave, to show which version you checked; then state how many clauses the clause list has and how many of them have no corresponding requirement in verify. At the end of the report, attach a clause mapping table: one row per clause in the clause list, with the IDs of the corresponding requirements; when one clause contains several provisions, one row per provision; write "None" where there is no corresponding requirement. The author fills the gaps from this table. Report only problems that would make delivery go wrong or impossible to judge, and over-specification found under item 8. Do not report wording, layout or style preferences; give at most three other improvement suggestions, marked "optional". When there are no problems, write "No issues found" directly, and list the scope you checked.
Write each issue with the following fields:
```text
Type: spec contradiction / spec undecided / spec ambiguous / spec missing item / fact mismatch / departs from source agreements / missing coverage / beyond spec / insufficient discriminating power / not executable / over-specification
Location: file and section, or requirement or scenario ID
Issue: one sentence
Basis: quote the source text
Impact: which reasonable implementation would be wrongly judged as passing, or wrongly judged as failing; for over-specification, the work it adds and why removing it lets no wrong implementation pass
Suggestion: the concrete change to verify; for a problem in the spec, give the change when the source agreements have a basis for it, and when they do not, write it as a question for the user to decide, with the options
```
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 |