pc-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.

See context and anti-pattern notes.

Inputs

I/O contract notes define required inputs and authority.

Process

Step 1: Structure the Document

Use the relevant template sections; mark inapplicable sections with a reason:

• product / feature scope documents: templates/prd.md
• technical design proposals: templates/rfc.md

1. Overview -- One paragraph explaining what this is and why it matters
2. Goals -- What success looks like (measurable)
3. Non-Goals -- Explicitly what this does NOT cover (prevents scope creep)
4. Product and system contract -- the user flows, domain rules, interfaces, rollout boundaries, and edge cases that downstream work must preserve
5. Security Considerations -- Threat vectors and mitigations
6. Testing Strategy -- How to verify this works
7. Rollout Plan -- How to ship safely
8. Open Questions -- Owner, decision stage, and the work each unresolved item blocks

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: Check ambiguity, contradictions, and unsupported assumptions
• Peer review: Have another PM or architect review for completeness
• Engineering review: Have the implementing team review for feasibility and questions
• Resolve questions that block the next authorized stage. Carry architecture decisions to design with owners; implementation waits for decisions its scope depends on. A spec review does not waive a stricter workflow gate.

Outputs

Produce only declared outputs at their documented quality boundary.

Quality Gate

• Applicable sections define the current contract without invented detail
• Open questions identify owners, decision stages, and dependent work
• Required reviewers approve the stated next stage; its blocking concerns are resolved
• Spec is versioned and accessible to all team members

Distribution

• Public install surface: skills/.curated
• Canonical authoring source: skills/01-specification/pc-spec-writing/SKILL.md
• This package is exported for npx skills add/update compatibility.
• Packaging stability: beta
• Capability readiness: beta
• Portability: portable_with_caveat
• Public caveat: Portable as skill guidance; full governance guarantees require the Prodcraft repository contracts and validation checks.