Product Specs Writer

Comprehensive product documentation expertise — from strategic PRDs to implementation-ready specifications that engineering teams can actually build from.

Philosophy

Great product specs bridge the gap between vision and execution. They're not bureaucratic documents; they're communication tools that align teams and prevent expensive misunderstandings.

The best product specifications:

1. Start with the why — Context before requirements
2. Are testable — Every requirement has clear acceptance criteria
3. Anticipate questions — Edge cases, errors, and constraints documented upfront
4. Evolve with the product — Living documents, not static artifacts
5. Respect the reader — Engineers, designers, and stakeholders can all understand them

How This Skill Works

When invoked, apply the guidelines in rules/ organized by:

• prd-* — Product Requirements Documents, vision, scope
• stories-* — User stories, personas, jobs-to-be-done
• criteria-* — Acceptance criteria, definition of done
• technical-* — Technical specifications, architecture decisions
• api-* — API specifications, contracts, versioning
• edge-* — Edge cases, error handling, failure modes
• design-* — Design handoff, component specs, interactions
• rollout-* — Feature flags, rollout plans, experiments
• metrics-* — Success metrics, KPIs, measurement plans
• maintenance-* — Documentation lifecycle, versioning, deprecation

Core Frameworks

Specification Hierarchy

┌─────────────────────────────────────────┐
│              VISION                     │  ← Why are we building this?
│         (Problem & Opportunity)         │
├─────────────────────────────────────────┤
│               PRD                       │  ← What are we building?
│      (Requirements & Constraints)       │
├─────────────────────────────────────────┤
│          USER STORIES                   │  ← Who benefits and how?
│       (Personas & Journeys)             │
├─────────────────────────────────────────┤
│      ACCEPTANCE CRITERIA                │  ← How do we know it's done?
│      (Testable Conditions)              │
├─────────────────────────────────────────┤
│      TECHNICAL SPECS                    │  ← How do we build it?
│   (Architecture & Implementation)       │
└─────────────────────────────────────────┘

Document Types by Audience

The INVEST Criteria (User Stories)

Specification Completeness Checklist

PRD Completeness:
├── Problem Statement         □ Clearly defined user pain
├── Success Metrics          □ Measurable outcomes defined
├── User Stories             □ All personas covered
├── Scope                    □ In-scope and out-of-scope clear
├── Constraints              □ Technical and business limits stated
├── Dependencies             □ External dependencies identified
├── Risks                    □ Known risks and mitigations
├── Timeline                 □ Milestones and deadlines set
└── Open Questions           □ Unknowns explicitly listed

Technical Spec Completeness:
├── Architecture             □ System design documented
├── Data Model               □ Schema and relationships defined
├── API Contracts            □ Endpoints and payloads specified
├── Edge Cases               □ Failure modes documented
├── Security                 □ Auth, encryption, compliance covered
├── Performance              □ SLAs and benchmarks defined
├── Monitoring               □ Observability strategy clear
└── Rollback Plan            □ Recovery procedures documented

Error Handling Taxonomy

Specification Templates

Minimal PRD Structure

# Feature: [Name]

## Problem
What user problem are we solving?

## Solution
High-level approach (1-2 paragraphs)

## Success Metrics
- Primary: [Metric] from X to Y
- Secondary: [Metric] from X to Y

## User Stories
- As a [user], I want [goal] so that [benefit]

## Scope
**In scope:** [List]
**Out of scope:** [List]

## Open Questions
- [ ] Question 1
- [ ] Question 2

User Story Template

**As a** [persona/user type]
**I want** [capability/action]
**So that** [benefit/value]

**Acceptance Criteria:**
- Given [context], when [action], then [result]
- Given [context], when [action], then [result]

**Edge Cases:**
- What if [edge case]? Then [behavior]

**Out of Scope:**
- [Explicit exclusion]

Anti-Patterns

• Spec by committee — Over-collaboration produces vague documents
• Premature optimization — Specifying implementation details too early
• Missing the why — Requirements without context for decisions
• Kitchen sink scope — Trying to solve everything in one release
• One-way documentation — Specs that don't get updated as learnings emerge
• Assumption blindness — Not documenting implicit assumptions
• Designer/Engineer telephone — No direct communication, only docs
• Success theater — Metrics chosen because they're easy, not meaningful
• Spec as contract — Treating specs as unchangeable legal documents
• Documentation debt — Outdated specs worse than no specs