yknothing 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