spec-writer ยท diff
v1.1.0 to v1.1.0
20 added, 8 removed. Audit A to A.
---
name: spec-writer
description: Generate numbered repo spec folders with clear requirements, implementation plans, and task lists for non-trivial project work.
version: 1.1.0
---
# Spec Writer Skill
## Intent
Use this skill to turn a rough repo change, feature idea, cleanup effort, or migration into a numbered spec folder with practical planning documents. The goal is to create a working spec package that another engineer can pick up and execute without guessing what the work means.
## Use When
- The user wants a new spec for a repo change, feature, refactor, migration, or workflow
- A project needs structured `requirements.md`, `plan.md`, and `tasks.md` documents
- The repo already uses numbered spec folders and new work should follow that pattern
- The request is large enough that ad hoc notes would be too loose
## Do Not Use When
- The change is tiny and does not need formal planning
- The repo has no spec workflow and the user only wants direct implementation
- The user wants a README, assessment, or changelog instead of an execution spec
- The available context is too thin to produce honest requirements and next steps
## Workflow
- 1. Read the repo context first.
- 2. Confirm where specs live and how numbering works.
- 3. Pick the next available spec number unless the user provided one.
- 4. Create a short kebab case spec folder name tied to the actual work.
- 5. Write the core documents:
+ 1. Read the repo context and Git status first; identify existing planning files and user edits.
+ 2. Inspect existing specs for work matching the user's goal before assigning a number. Compare scope and acceptance criteria, not just folder names. Reuse a matching stale spec when the requested update is authorized; do not create a duplicate merely because its status is old. If multiple specs match or reuse conflicts with the user's requested destination, ask which to use before writing.
+ 3. Confirm the spec root, numbering convention and complete relevant directory listing. With incomplete or inaccessible numbering evidence, request the missing context or provide an unnumbered proposal; do not claim the next number is verified.
+ 4. Only when no matching spec should be reused, use an available user-requested number or otherwise select the next unused number, then choose a short kebab case name. Check both the number across existing folders and the exact destination, including untracked files. If a requested number or destination is occupied by other work, report the conflict and ask for a destination choice; do not overwrite or silently renumber. Recheck immediately before writing; if the destination changed since inspection, stop the write and report the conflict.
+ 5. Write or update only the authorized planning documents:
- `requirements.md`
- `plan.md`
- `tasks.md`
6. Keep each file practical:
- requirements explain the problem, scope, constraints, and success criteria
- plan explains the implementation approach, touched areas, risks, and validation path
- tasks break the work into ordered, checkable execution steps
7. Make assumptions explicit. Do not pretend unknown details are settled facts.
- 8. Recheck that the spec matches the live repo, existing conventions, and the user's real goal.
+ 8. Recheck that the spec matches the live repo, existing conventions, and the user's real goal. Verify acceptance-to-validation traceability and preservation of files outside the authorized planning scope.
## Spec Status
Give every spec a visible state so a folder listing tells the truth about the work. Put a status line at the top of `requirements.md`:
```text
Status: draft | in progress | done | abandoned
Last updated: YYYY-MM-DD
```
- When asked to update or review specs, update the status line as part of the change. When creating a new spec, check whether an existing spec already covers the work and is merely stale; updating its status beats creating a duplicate.
+ A new execution spec starts as `draft` with unchecked implementation tasks. Writing or reviewing a plan does not implement the feature or establish that checks passed. Change status only to reflect supported evidence and an authorized update; never mark implementation `done` because planning is complete. For a review-only request, recommend status corrections in the response instead of editing files. When reusing a stale spec, preserve completed-work evidence and explain any proposed status correction; do not reset its history automatically.
## Template Variants
Shape the documents to the work type instead of using one generic skeleton:
- `feature`: requirements emphasize user-facing behavior and acceptance criteria; plan covers integration points and new surface area
- `refactor`: requirements define behavior that must not change and how that is verified; plan emphasizes sequencing and safe checkpoints; tasks alternate change and verify steps
- `migration`: requirements define the end state and cutover criteria; plan covers dual-running, rollback, and data integrity; tasks include a rehearsal step before the real cutover
Name the variant in `requirements.md` so the reader knows which lens the spec uses.
## Requirements Guidance
- State the problem in plain language
- Define in scope and out of scope
- List constraints from the repo, tooling, platform, or user instructions
- Include acceptance criteria that can actually be verified
- Keep wording concrete enough that implementation decisions can be judged against it
## Plan Guidance
- Name the files, modules, folders, scripts, or systems likely to change
- Explain the intended implementation shape without drifting into code
- Call out dependencies, sequencing, migration concerns, and rollback or safety issues where relevant
- Include a validation section with realistic checks such as tests, linting, manual flows, or document review
## Task Guidance
- Break work into an execution order that another engineer can follow
- Prefer tasks that map to real deliverables, not vague activity labels
- Separate implementation, validation, and documentation work when that helps execution
- Keep tasks small enough to complete and review, but not so small that the list becomes noise
- Give each task a rough size of `S` (under an hour), `M` (half a day), or `L` (a day or more) so the spec communicates effort, not just steps; an `L` task is usually a sign it should be split
## Constraints
- Match the repo's existing spec layout if one already exists
- Prefer editing existing planning structure over inventing a new one
- Use direct language and skip filler
- Do not pad specs with generic boilerplate
- Do not hide major assumptions or risks
- - If numbering or naming is ambiguous, choose the clearest consistent option
+ - If numbering, matching scope or destination intent is ambiguous, ask for the minimum decision before writing; do not silently choose between conflicting user intentions.
+ - Preserve staged, unstaged and untracked user edits. Read the current planning files before a targeted update; do not replace whole documents or alter unrelated files merely to fit a template. If proposed changes conflict with user work, present the conflict and wait for direction.
+ - File access is not write authorization. Return a proposal when writing is not requested or authorized; do not create folders for a review-only task.
+ ## Acceptance-to-validation traceability
+
+ Use stable acceptance-criterion identifiers (for example `AC-1`) in `requirements.md`, retaining existing identifiers when updating a spec. In `tasks.md`, map every criterion to at least one concrete validation task with the check or procedure and expected observable result. A table such as `Criterion | Validation task | Check | Expected result` is sufficient; follow an equivalent existing repository convention instead of duplicating it. Shared validation tasks may cover several criteria if each mapping is explicit.
+
+ Before delivery, check for unmapped criteria, references to nonexistent criteria/tasks, and vague checks without an expected result. Mark unavailable validation as planned or blocked with its prerequisite; do not claim it ran or check it off. Keep implementation tasks separate from proof of acceptance. Summarize the chosen reuse/new-spec decision, destination, changed files, open decisions and checks actually performed.
+
## References
- `shared/skill-standard.md`
- Existing `specs/` folders in the target repo
- Any repo handoff docs such as `assessment.md`, `project-analysis.md`, or roadmap files if they exist
## Help And Examples
Use this skill when the user wants a real execution spec instead of loose notes.
Minimum useful input:
- the repo or project context
- what needs to be built, changed, or cleaned up
- any scope limits or constraints
Example prompts:
```text
Use spec-writer to create the next numbered spec for moving this repo from ad hoc scripts to a module layout with tests and CI.
```
```text
Create a spec folder for adding OAuth refresh handling and export retry logic to this CLI project.
```
```text
Write a numbered repo spec with requirements, plan, and tasks for a README audit plus stale doc cleanup.
```
## Validation Checklist
- The spec folder name and number fit the repo's existing pattern
- `requirements.md`, `plan.md`, and `tasks.md` are all present
- The requirements are specific enough to judge success
- The plan matches the actual repo context
- The tasks are ordered, practical, and executable
+ - Matching specs were inspected before numbering; occupied or uncertain destinations remain untouched until resolved
+ - Existing user edits and files outside the authorized planning scope are preserved
+ - Every acceptance criterion maps to a validation task with an observable expected result; no dangling mappings remain
+ - Planning status and task checkboxes distinguish proposed work from verified implementation
## Host Capabilities
Use only tools, files, conversation history, and connected services actually available and authorized in the current host. If browsing, image/document inspection, code execution, persistent storage, or a related skill is unavailable, state the limitation and request the needed input or provide manual steps. Never claim a lookup, save, execution, publication, or installation occurred without evidence. Preserve the domain safety and confirmation rules above.
## Capability Contract
Read `capabilities.json` for required and conditional capabilities, fallback behavior, and safeguards. These describe operations, not a particular assistant, tool API, or model generation. Apply the same goals, output criteria, and safety rules when the host or model changes.