| name | test-spec |
| version | 1.0.0 |
| schema-version | skill-readability-v1 |
| description | Generate a traceable test specification from an approved feature spec and execution plan before writing test code or production code. Use to map requirements, examples, edge cases, architecture boundaries, and milestones into concrete tests.
|
| argument-hint | ["feature spec path","plan path","or feature name"] |
Test spec authoring
You are designing the proof before implementation.
The test spec defines how the team will know the implementation satisfies the behavioral contract.
Workflow role
- role_name: test-spec
- stage: authoring
- upstream: approved spec, spec-review findings, approved plan, and relevant architecture or ADR records when present
- downstream: test-spec-review
- summary: Design the proof mapping requirements, examples, edge cases, architecture boundaries, and milestones to tests before implementation.
- must_not_claim: implementation completion, code-review approval, verification, branch readiness, or PR readiness.
Stop conditions
Stop and report the blocker instead of producing a test spec when:
- the source spec is unreviewed or unstable, unless the user explicitly requests isolated test-planning output and the limitation is recorded;
- the relevant spec-review outcome explicitly marked eventual
test-spec readiness as not-ready.
Inputs to read
Read:
- approved feature spec;
- spec-review findings;
- architecture doc and ADRs when relevant;
- concrete execution plan;
AGENTS.md and CONSTITUTION.md if present;- existing test conventions, fixtures, helpers, and CI commands;
- related tests for similar behavior.
Output path
Prefer:
specs/slug.test.md
Artifact placement
Use the project workflow guide for artifact locations when placement matters.
Lookup order:
- explicit user path or change ID;
- active plan, change metadata, reviewed artifact path, or current artifact metadata;
- known governing spec or schema constraint when directly relevant;
- project workflow guide artifact-location table, such as the
docs/workflows.md artifact-location table when present;
- this skill's portable default path;
- block on ambiguity.
This discovery order is subordinate to the source-rank rule in the project workflow guide when sources conflict.
Do not broad-search authoritative documents just to find paths. Use docs/workflows.md as the path index when present in this project, and consult specs or schemas only when they govern exact shape, placement, or a detected conflict.
Resource map
- COPY
assets/test-spec-skeleton.md when creating or fully rewriting a test spec.
Fill: title, sections, coverage maps, test cases, artifacts, and readiness.
Do not emit unfilled placeholders.
- COPY
assets/test-case.md when adding each test case.
Fill: test ID, title, covers, level, command IDs, setup, steps, expected result, failure proof, evidence artifact, automation location, and required milestone.
Do not emit unfilled placeholders.
- COPY
assets/coverage-map-row.md when adding requirement or example coverage-map rows.
Use the Requirement coverage row variant for the requirement coverage map.
Use the Example coverage row variant for the example coverage map.
Fill: fields exactly as shown by the selected variant.
Do not add a Level column to the example coverage map.
Do not emit unfilled placeholders.
- COPY
assets/validation-command-row.md when adding each validation-command ledger row.
Fill: command ID, command, classification, owner, owning milestone, first required milestone, failure behavior, zero-test behavior, evidence artifact, and safe-mode or side-effect boundary.
Do not emit unfilled placeholders.
- COPY
assets/milestone-proof-row.md when adding each milestone proof-map row.
Fill: milestone, required test IDs, manual proof IDs or none, command IDs or none, evidence artifacts, required-before gate, and notes.
Do not emit unfilled placeholders.
Generated Markdown readability
When this skill creates or updates generated or generator-shaped Markdown:
- Use semantic source lines for human-facing prose; one sentence or natural clause per source line when practical.
- Preserve stable IDs for requirements, findings, commands, milestones, and evidence; use tables for repeated mappings.
- Keep commands fenced or table-owned when they carry proof.
- Diagrams are optional. Use them only when they reduce cognitive load and map to real artifacts, stages, components, actors, or states.
- Do not require manual-proof contracts from this readability guidance alone; use governing project rules when manual proof is otherwise required.
Required sections
| Section | Requirement |
|---|
| Status | Use <test spec status>. |
| Related spec and plan | Include the related spec and plan. |
| Input artifact identities | Include when implementation or code-review will rely on the test spec. Record input kind, path, status or review state, and identity for the feature spec, relevant review records, plan, plan review, and architecture or ADR inputs when applicable. |
| Testing strategy | Cover unit, integration, end-to-end, smoke, manual, contract, and migration strategy. |
| Requirement coverage map | Every requirement ID maps to one or more tests or explicit manual verification. |
| Example coverage map | Every example maps to a test when feasible. |
| Edge case coverage | Include edge case coverage. |
| Validation commands | Required whenever the test spec names, references, or depends on validation commands. If no commands are part of the proof map, say so explicitly with rationale. |
| Milestone proof map | Required when the approved plan has milestones, staged validation, staged commands, or milestone-specific code-review boundaries. If not applicable, state Not applicable or equivalent rationale. |
| Test cases | Include test cases with stable IDs. |
| Fixtures and data | Include fixtures and data. |
| Mocking/stubbing policy | Include mocking/stubbing policy. |
| Migration or compatibility tests | Include when relevant. |
| Observability verification | Include when logs, metrics, traces, or audit events are required. |
| Security/privacy verification | Include when relevant. |
| Performance checks | Include when relevant. |
| Manual QA checklist | Include when automation is insufficient. |
| What not to test | Include what not to test and why. |
| Uncovered gaps | Include gaps that must return to spec or architecture. |
| Next artifacts | Include planned next steps while the test spec remains draft or active. |
| Follow-on artifacts | Include actual downstream artifacts or terminal disposition. If present before any real follow-ons exist, say None yet. |
| Readiness | Include truthful next-stage or active-proof-surface wording. |
Test case format
Use:
T1. Title
- Covers: R1, R3, E2
- Level: <test case level>
- Command IDs: <command IDs or none>
- Fixture/setup:
- Steps:
- Expected result:
- Failure proves:
- Evidence artifact:
- Automation location:
- Required by milestone:
If a test case uses or depends on a validation command, reference at least one Command ID from Validation commands. Do not rely only on raw command strings.
Validation command ledger
Use Validation commands whenever the test spec names, references, or depends on validation commands. The section is optional only when no commands are part of the proof map, and then it must state that no validation commands are part of the proof map with rationale.
Use stable Command IDs such as CMD1, CMD2, and CMD3. Reference those IDs from test cases, milestone proof-map rows, and evidence notes.
Command classification is a closed enum:
existing/configured
planned-for-implementation
release-owned
ci-owned
external-owned
not-applicable
Each validation-command row must record:
- Command ID;
- command;
- classification;
- owner;
- owning milestone;
- first required milestone;
- failure behavior;
- zero-test behavior;
- evidence artifact;
- safe-mode or side-effect boundary.
Command rules:
- Every named, referenced, or depended-on validation command gets a stable Command ID.
- A planned command must use
planned-for-implementation and name an owner, owning milestone, and first required milestone.
- A planned command is not required before its first required milestone.
- A command expected to run tests must define zero-test behavior.
- Commands with network, publication, destructive, or external side effects must state the safe-mode or side-effect boundary.
- Missing required commands block implementation or milestone closeout according to the milestone proof map.
- During authoring, inspect known manifests and existing scripts when feasible, but do not execute validation commands.
Milestone proof map
Use Milestone proof map when the approved plan has milestones, staged validation, staged commands, or milestone-specific code-review boundaries.
Each implementation milestone must map to test IDs, manual proof IDs or none, command IDs or none, evidence artifacts, and the gate where proof is required. A milestone may use an explicit not-applicable rationale only when no proof entry applies.
Milestone proof-map rules:
- Identify which proof is required before milestone code-review.
- Identify proof deferred to later milestones, verify, release-owned evidence, or another explicitly named stage.
- Do not let a milestone rely on a command whose ownership starts in a later milestone unless the row explicitly marks the command as planned and not yet required.
Coverage rules
| Coverage target | Rule |
|---|
MUST requirements | Every MUST requirement needs coverage. |
| Error behavior | Every error behavior needs coverage. |
| Migration or compatibility claims | Every migration or compatibility claim needs coverage or explicit manual verification. |
| Architectural boundaries that could break wiring | Every architectural boundary that could break wiring needs an integration or contract test. |
| Bugs | Bugs require a regression test that fails before the fix when feasible. |
Closed enums
Test spec status:
draft
active
abandoned
superseded
archived
Test case level:
unit
integration
e2e
smoke
manual
Coverage map level:
unit
integration
e2e
smoke
manual
contract
migration
Output skeleton
# <Test spec title>
COPY `assets/test-spec-skeleton.md` for the full test-spec structure. Use
`assets/test-case.md`, `assets/coverage-map-row.md`,
`assets/validation-command-row.md`, and `assets/milestone-proof-row.md`
for repeated structures.
Required sections are listed above. Do not emit unfilled placeholders.
Rules
- Do not invent behavior not specified.
- Do not mark a requirement covered by a test that does not assert it.
- Do not rely only on snapshots for behavioral requirements.
- Do not skip integration tests where the risk is at a boundary.
- Do not use
reviewed or long-lived complete as durable test-spec states. Move from draft to active when implementation or review is relying on the test spec, then close out to archived, superseded, or abandoned when it is no longer the active proof-planning surface.
- Preserve
Next artifacts as planning history. Use Follow-on artifacts for actual downstream artifacts, replacement, or terminal closeout.
- Do not hide untestable requirements; send them back to
spec-review.
- Do not treat downstream implementation readiness as a substitute for approved spec-review findings and concrete plan context.
- When changed boundaries still require approved architecture or ADR input, return the work to the appropriate upstream gate instead of guessing.
- Formal workflow-managed test specs route to
test-spec-review before implementation.
- Under
implementation-through-verify, the workflow may run deterministic test-spec settlement after authoring. Settlement records coverage, uncovered gaps, validation commands, and input artifact identities; it does not replace required test-spec-review.
- If settlement or
test-spec-review reveals upstream ambiguity or stale inputs, pause instead of authorizing implementation. The first milestone's code-review rechecks the recorded input artifact identities before accepting the implementation review surface.
Evidence collection efficiency
Use summary and stable-ID first reasoning before broad reads or raw excerpts. Prefer check IDs, requirement IDs, test IDs, file paths, counts, and line citations when inspecting large files, repeated scans, generated output, or validation output. Read exact ranges after locating relevant lines, then expand only when the narrower evidence is insufficient.
When full-file read is required
Read the full file when the whole file is the review target, the relevant section cannot be isolated safely, surrounding context can change the conclusion, bounded searches disagree or produce incomplete evidence, or a behavior-changing edit depends on the whole source-of-truth artifact.
Expected output
- test spec path;
- grouped test cases;
- requirement-to-test coverage map;
- fixtures and commands;
- explicit exclusions;
- uncovered gaps, if any;
- readiness statement for
test-spec-review.
