spec-writing
Spec Writing
A good spec eliminates ambiguity. Engineers should be able to build from it without guessing.
Context
Spec writing is the heaviest specification skill, used primarily in spec-driven and waterfall workflows. In greenfield work, it can be used in a lighter form to lock the first-release contract before architecture begins. In brownfield work, it documents current behavior, target-state boundaries, or modernization constraints that downstream design and implementation must not rediscover from scratch.
Do not reach for this skill during routine agile story refinement. In day-to-day sprint work, prefer lightweight requirements, acceptance criteria, and task breakdown unless the change is large enough to need a shared written contract.
The core contract of this skill is not "write more detail." It is to freeze the boundary between:
- what release 1 must do
- what is explicitly out of scope
- which constraints downstream architecture must preserve
- which open questions remain visible instead of being silently guessed away
Inputs
- requirements-doc -- produced by the preceding skill in the lifecycle
- domain-model -- produced by the preceding skill in the lifecycle
Process
Step 1: Structure the Document
Use a consistent template:
- product / feature scope documents:
templates/prd.md - technical design proposals:
templates/rfc.md
- Overview -- One paragraph explaining what this is and why it matters
- Goals -- What success looks like (measurable)
- Non-Goals -- Explicitly what this does NOT cover (prevents scope creep)
- Product and system contract -- the user flows, domain rules, interfaces, rollout boundaries, and edge cases that downstream work must preserve
- Security Considerations -- Threat vectors and mitigations
- Testing Strategy -- How to verify this works
- Rollout Plan -- How to ship safely
- Open Questions -- Unresolved items (must be empty before implementation)
Step 2: Write for Your Audience
Engineers are the primary readers. Be precise:
- Include data types and validation rules
- Specify error handling for each operation
- Define state transitions explicitly
- Use diagrams for complex flows (sequence diagrams, state machines)
Precision does not mean implementation detail. Keep the spec at the contract layer:
- required behavior
- supported and unsupported flows
- release boundaries
- rollout and coexistence constraints
- unresolved questions that architecture must preserve
Step 3: Define Scope Boundaries
For every feature, explicitly state:
- What IS included in this spec
- What is NOT included (and where it will be addressed)
- What assumptions you're making (and how to validate them)
Step 4: Review Cycle
- Self-review: Re-read after 24 hours with fresh eyes
- Peer review: Have another PM or architect review for completeness
- Engineering review: Have the implementing team review for feasibility and questions
- Resolve all open questions before approving for implementation
Outputs
- spec-doc -- produced by this skill
Quality Gate
- All sections of the template completed
- Open Questions section is empty (all resolved)
- Engineering team has reviewed and has no blocking concerns
- Spec is versioned and accessible to all team members
Anti-Patterns
- Spec that's actually a novel -- If it's over 15 pages, split into smaller specs. No one reads a 50-page spec.
- Spec without non-goals -- Without explicit non-goals, scope will expand invisibly.
- Spec as waterfall artifact -- A spec should be a living document, updated as understanding evolves.
- Implementation details in spec -- Spec defines the contract boundary, not the service classes, schema migrations, or framework internals.
- Open-question laundering -- Writing as if unresolved sync, compatibility, or rollout assumptions are already closed.
Related Skills
- requirements-engineering -- provides the requirements to specify
- domain-modeling -- provides domain model referenced in spec
- system-design -- consumes spec for architecture decisions
- task-breakdown -- breaks spec into implementable tasks
Distribution
- Public install surface:
skills/.curated - Canonical authoring source:
skills/01-specification/spec-writing/SKILL.md - This package is exported for
npx skills add/updatecompatibility. - Packaging stability:
beta - Capability readiness:
beta
More from yknothing/prodcraft
system-design
Use when reviewed requirements or specifications are ready and the team must decide high-level architecture, component boundaries, integration seams, or brownfield coexistence strategy before API design, technology selection, or task planning.
6intake
The mandatory gateway for all new engineering work. Triage and route new products, apps, features, migrations, tech-debt, or any 'not sure where to start' request to the correct lifecycle path. Use before starting design or implementation. Do not use for ongoing tasks, specific debugging, or PR reviews.
6feature-development
Use when a reviewed task slice has tests or acceptance targets and the team must turn it into a small, mergeable implementation increment without expanding scope, breaking contracts, or hiding release-boundary risk.
6monitoring-observability
Use when a live service or newly delivered release needs actionable telemetry, dashboards, and alerts that expose real user-impactful boundaries, especially when brownfield coexistence rules, unsupported-flow safety, rollback health, or queue/backfill behavior must be visible before incidents escalate.
6incident-response
Use when a live production issue needs coordinated containment, severity triage, stakeholder communication, and evidence capture, especially when a recent release, brownfield coexistence rules, rollback decisions, or unresolved contract boundaries must be handled before root-cause work.
6task-breakdown
Use when reviewed architecture or API contracts must be decomposed into implementation-ready work items, especially when sequencing, reversible brownfield increments, dependency mapping, and vertical slices must be explicit before coding begins.
6