Write Specs
Specification
The words
,
,
,
,
,
,
,
,
, and
are interpreted as described in
RFC 2119.
Purpose
Use this skill to turn loose project intent into a specification that implementors can build against and reviewers can validate. Prefer explicit contracts over narrative explanation. Make hidden decisions visible.
Core Workflow
-
Ground the spec in available evidence.
- Read any linked docs, code, issues, PRs, diagrams, user notes, or product context before drafting.
- Separate confirmed facts from assumptions.
- Mark unresolved decisions as open questions only when they materially affect implementation.
-
Define the contract before the design details.
- State purpose, status, audience, and scope.
- If the spec uses , , , , , , , , , or , use those key words only with their RFC 2119 meanings.
- Include a section in the resulting spec that explicitly states that these words are interpreted as described in RFC 2119.
- Clarify what is implementation-defined and require implementations to document those choices.
-
Establish boundaries.
- Write a problem statement that names the operational or user problems being solved.
- List goals and non-goals.
- Identify responsibility boundaries: what this system owns, what external systems own, and what humans or operators own.
-
Name the system shape.
- Define main components and their responsibilities.
- Define abstraction layers when useful, such as policy, configuration, coordination, execution, integration, storage, UI, and observability.
- Name external dependencies and required environment assumptions.
-
Specify the domain model.
- List entities with field names, types, nullability, defaults, and stable identifiers.
- Define normalization rules, derived values, ordering rules, uniqueness constraints, and path or naming constraints.
- State which identifier is used for logs, storage, API calls, UI display, and internal maps.
-
Specify configuration and repository contracts.
- Define config file discovery, parsing rules, schema, defaults, validation, environment-variable resolution, and unknown-key behavior.
- State whether config changes apply dynamically or require restart.
- Define behavior for invalid, missing, or partially valid config.
-
Specify lifecycle and state.
- Define state machines or lifecycle phases for important entities.
- List transition triggers, guards, side effects, retries, terminal states, and recovery behavior.
- Distinguish external state from internal runtime state.
-
Specify workflows and algorithms.
- Describe important flows in deterministic order.
- Include pseudocode only where sequencing, concurrency, retry, locking, or recovery would otherwise stay ambiguous.
- Define sorting, dispatch, batching, deduplication, idempotency, timeout, cancellation, and backoff behavior when relevant.
-
Specify failure behavior.
- List failure modes by operation.
- Define whether each failure aborts, retries, degrades, preserves last-known-good state, surfaces to operators, or requires manual intervention.
- Include cleanup behavior and what must remain durable after failure.
-
Specify safety and security invariants.
- State what must never happen.
- Define trust assumptions, permissions, sandboxing or approval posture, data retention, secret handling, and filesystem or network boundaries.
- Keep policy choices explicit when one universal answer is not appropriate.
-
Specify observability.
- Define required logs, metrics, events, traces, status surfaces, and operator-visible errors.
- Include stable field names for structured logs when possible.
- State what information must be available to debug a failed or partial run.
-
Specify compatibility and migration.
- Define backward-compatibility and forward-compatibility requirements for APIs, config, storage, file formats, user workflows, and operational behavior.
- Identify breaking changes, required migrations, rollout order, fallback behavior, downgrade behavior, and data retention or cleanup expectations.
- Mark compatibility or migration behavior as only when a single universal policy is not appropriate, and require implementations to document the selected policy.
-
Finish with validation.
- Provide conformance tests, acceptance criteria, smoke checks, and a definition of done.
- Split required core behavior from optional extension behavior.
- Include negative tests for invalid config, failures, retries, permissions, state transitions, compatibility boundaries, migrations, and boundary enforcement.
Spec Structure
Use this default outline unless the project clearly needs another shape:
markdown
# <Project or Feature> Specification
Status: Draft
Audience: Implementors and reviewers
Purpose: <one sentence>
## Specification
The words `MUST`, `MUST NOT`, `REQUIRED`, `SHALL`, `SHALL NOT`, `SHOULD`, `SHOULD NOT`, `RECOMMENDED`, `MAY`, and `OPTIONAL` are interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
## 1. Problem Statement
## 2. Goals and Non-Goals
## 3. System Overview
### 3.1 Main Components
### 3.2 Abstraction Layers
### 3.3 External Dependencies
## 4. Domain Model
## 5. Configuration and Contracts
## 6. Lifecycle and State
## 7. Core Workflows
## 8. Failure Handling
## 9. Safety and Security
## 10. Observability
## 11. Compatibility and Migration
## 12. Testing and Validation Matrix
## 13. Implementation Checklist
## 14. Open Questions
Remove sections that truly do not apply, but do not remove a section merely because the answer is inconvenient or still unknown. Use
with a short reason when omission would hide a design decision.
Detail Standard
A concrete spec should answer these questions wherever relevant:
- What is the exact input and output?
- Who owns this behavior?
- What names, identifiers, paths, states, or API fields are stable?
- What defaults apply?
- What is validated, when, and by whom?
- What happens when data is missing, malformed, stale, duplicated, or unauthorized?
- What happens on retry, restart, cancellation, timeout, and partial success?
- What changes must remain compatible, and what migration or rollout path is required when they cannot?
- What is logged or surfaced to an operator?
- How can another implementor prove conformance?
Writing Rules
- Use precise requirement language for behavior that must be testable.
- Do not use RFC 2119 key words in all caps unless the statement is intended to be normative and testable.
- Prefer tables or field lists for schemas, states, config keys, and errors.
- Keep examples realistic and small.
- Put policy choices in the spec instead of burying them in prose.
- Preserve useful ambiguity only by labeling it and requiring documentation.
- Avoid implementation detail when it does not affect interoperability, safety, user-visible behavior, or validation.
- End with concrete acceptance criteria, not a summary.
Output Modes
When creating a spec artifact, write it to
unless the user specifies another filename, path, or delivery format.
When the user asks for a full spec, produce the complete document.
When the user asks to prepare for a spec, produce:
- the proposed outline,
- the known contracts and decisions,
- the missing decisions that block implementation,
- the evidence still needed from code, docs, product, or operations.
When the user asks to review an existing spec, prioritize missing contracts, ambiguous behavior, untestable requirements, unsafe omissions, and places where goals conflict with lifecycle, failure, or validation sections.