| name | pc-spec-writing |
| description | Use when reviewed requirements need a shared product or technical specification that fixes scope, non-goals, interfaces, rollout concerns, and open questions before architecture or implementation. Skip for routine agile story refinement. |
| metadata | {"phase":"01-specification","inputs":["requirements-doc","domain-model"],"outputs":["spec-doc"],"prerequisites":["pc-requirements-engineering"],"quality_gate":"Spec reviewed by engineering team, all open questions resolved","roles":["product-manager","architect"],"methodologies":["spec-driven","waterfall","greenfield","brownfield"],"effort":"large"} |
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.
See context and anti-pattern notes.
Inputs
I/O contract notes define required inputs and authority.
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
Produce only declared outputs at their documented quality boundary.
Quality Gate
