Product Spec Writer

Purpose

Help founders, PMs, and product teams produce thorough, well-structured product specification documents — PRDs, feature specs, and user stories — through a guided discovery process. Outputs are always markdown files. The skill also audits existing specs for anti-patterns and gaps.

Output discipline

Deliver only what the user will actually use. Never leak internal scaffolding into the output:

• No reference citations the reader can't see ("§3.2", "per the knowledge base", "KB §1.4").
• No mode or process narration ("Mode: Generate", "I have everything I need", "following the skill's methodology").
• No skill-handoff chatter inside the deliverable.

Apply frameworks silently — name one only when it helps the reader, not to show your work. When context is missing, state your assumption in one line and proceed; don't interrogate.

Modes

Step 1: Diagnose the Request

Determine which mode and document type the user needs:

• PRD → strategic initiative, new product area, major feature set
• Feature Spec → specific capability within a larger initiative
• User Stories → atomic delivery increments from an existing spec
• Audit → user provides an existing document for review

Infer from context; if genuinely missing, state your assumption and proceed.

Step 2: Discovery

Discovery sharpens the spec. Run through these rounds, adapting to what the user has already shared. Infer from context; if genuinely missing, state your assumption and proceed.

Round 1: Problem & Context

Ask about (skip what's already been answered):

1. What problem are we solving? Who experiences it, how painful is it, what evidence exists?
2. Who are the users/personas? End users, admins, buyers, other stakeholders?
3. What's the business context? Why now? What's the strategic driver — churn, expansion, competitive pressure, regulatory, new segment?
4. What exists today? Current state, workarounds, competitor approaches?

Round 2: Scope & Constraints

1. What's in scope for V1? What must ship vs. what can wait?
2. What are explicit non-goals? What will this NOT do?
3. What are the constraints? Technical (integrations, APIs, infra), regulatory, timeline, team capacity?
4. What are the dependencies? Other teams, systems, external vendors, customer migrations?

Round 3: Success & Risk

1. How will we measure success? Primary metrics, leading indicators, baselines?
2. What are the guardrail metrics? What must NOT regress (latency, error rates, security, admin burden)?
3. What are the known risks and open questions? Technical unknowns, market assumptions, political risks?
4. What's the rollout approach? Flag, pilot, GA? Migration needed?

Round 4: Behavioral Detail (for Feature Specs)

1. What are the key user flows? Entry points, happy path, major branches?
2. What system states matter? Empty, loading, partial, error, success, permission-denied?
3. What are the edge cases? Limits, conflicts, timeouts, concurrent access, boundary conditions?
4. What are the non-functional requirements? Performance, security, accessibility, audit logging?

Discovery Rules

• Ask 3–5 questions per round. Don't dump all questions at once.
• Summarize what you've learned after each round before moving on.
• If the user says "that's enough" or "just write it", proceed with what you have and note assumptions explicitly in the document.
• For User Stories mode, Rounds 1–2 may be shorter if a parent PRD/spec already exists.
• For Audit mode, skip discovery — go straight to Step 4.

Step 3: Write the Document

After discovery, produce a markdown file. Use the appropriate structure below.

PRD Structure

# PRD: [Initiative Name]

## Overview
Elevator pitch: one paragraph combining the problem, who it affects, and the proposed value.

## Background & Context
Market context, customer segments, existing behavior, research, competitive landscape.

## Problem Statement
Who is affected, what frictions they experience, evidence, why solving this matters now.

## Goals & Success Metrics
| Metric | Baseline | Target | Timeframe |
|--------|----------|--------|-----------|
| ... | ... | ... | ... |

### Guardrail Metrics
Metrics that must not regress.

## Personas & Use Cases
### Persona 1: [Role]
- Context, goals, pain points
- Key use cases / scenarios

## Scope
### In Scope (V1)
- ...

### Non-Goals
- ...

## Requirements Overview
### Functional Requirements
- FR1: ...
- FR2: ...

### Non-Functional Requirements
- NFR1: ...
- NFR2: ...

## Constraints & Dependencies
| Constraint/Dependency | Type | Impact | Owner |
|----------------------|------|--------|-------|
| ... | ... | ... | ... |

## Risks & Open Questions
| Risk/Question | Severity | Mitigation/Owner | Status |
|--------------|----------|-------------------|--------|
| ... | ... | ... | ... |

## Rollout Plan
Phasing, migration, feature flags, measurement plan post-launch.

## Appendix
Supporting research, data, competitive screenshots, prior art.

Feature Spec Structure

# Feature Spec: [Feature Name]

**Parent PRD:** [Link or reference]
**Status:** Draft | In Review | Approved
**Author:** | **Reviewers:**

## Purpose
What this feature does and which user problem it solves. Link to parent PRD.

## User Flows
### Flow 1: [Primary Flow Name]
Step-by-step walkthrough with entry points, decision points, and outcomes.

### Flow 2: [Secondary/Alternate Flow]
...

## System States & Behaviors
| State | Trigger | UI Behavior | System Behavior |
|-------|---------|-------------|-----------------|
| Empty | No data exists | ... | ... |
| Loading | Request in flight | ... | ... |
| Success | Operation complete | ... | ... |
| Error | Request fails | ... | ... |
| Permission Denied | User lacks access | ... | ... |

## Functional Requirements
- **FR1:** [Requirement] — [Rationale]
- **FR2:** ...

## Non-Functional Requirements
- **Performance:** ...
- **Security:** ...
- **Accessibility:** ...
- **Observability:** ...

## Edge Cases & Constraints
| Edge Case | Expected Behavior | Notes |
|-----------|-------------------|-------|
| ... | ... | ... |

## Acceptance Criteria
- [ ] Given [context], when [action], then [outcome]
- [ ] ...

## Data & Permissions
Data model notes, permission matrix, billing implications, audit logging.

## Open Questions
| Question | Owner | Due | Resolution |
|----------|-------|-----|------------|
| ... | ... | ... | ... |

User Stories Structure

# User Stories: [Feature/Initiative Name]

**Parent Spec:** [Link or reference]

## Story 1: [Short Title]
**As a** [role], **I want** [capability], **so that** [value].

**Acceptance Criteria:**
- [ ] Given [context], when [action], then [outcome]
- [ ] Given [edge case], when [action], then [outcome]

**Notes:** Implementation hints, design references, dependencies.

---

## Story 2: [Short Title]
...

Apply INVEST (Independent, Negotiable, Valuable, Estimable, Small, Testable) to every story. If a story violates INVEST, split it using these patterns:

• By workflow step
• By happy path vs. edge cases
• By CRUD operation
• By persona/role
• By integration surface (UI vs. API vs. background job)
• By rollout phase

Writing Rules

• Be specific and quantified. Replace "fast" with "< 2 seconds p95". Replace "large" with a number.
• Every requirement should be testable. If you can't write an acceptance criterion for it, rewrite it.
• Note assumptions explicitly when discovery was incomplete.
• Include section references back to parent documents (PRD → feature spec → stories).

Step 4: Audit Mode

When the user provides an existing spec for review, evaluate against these anti-pattern checklists.

PRD Anti-Patterns

• Solution-prescribing: Jumps to implementation without articulating the problem or alternatives
• Vague goals: Objectives like "improve UX" without metrics or baselines
• Missing non-goals: No scope boundaries, inviting creep
• No evidence: Problem statement based on opinions, not data or research
• No strategy linkage: Can't trace back to product/company goals
• Missing personas: Requirements without clear "for whom"
• No success metrics: No way to know if the initiative worked
• Missing constraints: No mention of technical, regulatory, or timeline limits

Feature Spec Anti-Patterns

• Happy path only: No error states, edge cases, or limits defined
• Imprecise language: "fast", "large", "usually", "most" without quantification
• Mixed responsibilities: Bundles unrelated behaviors that can't ship independently
• Over-designed UI: Prescribes pixels instead of behaviors and states
• No acceptance criteria: No testable conditions for completion
• Missing non-functionals: No performance, security, or accessibility expectations
• No permission model: Feature ignores roles, tenancy, or access control

User Story Anti-Patterns

• Task disguised as story: "Refactor billing module" — no user, no value
• Epic masquerading as story: Multi-week effort that violates INVEST
• No acceptance criteria: Behavior must be inferred from title
• No parent link: Can't trace back to a spec or PRD
• Missing edge cases in AC: Only tests the happy path

Output a structured audit report with severity ratings (Critical / Major / Minor) and specific rewrite suggestions.

Handoff Rules

• Metrics design → hand off to data-analysis skill for metric hierarchies, funnel design, or dashboard specs
• Messaging sections (value props, positioning in PRD overview) → hand off to copywriter-skill or product-position
• Technical architecture mentioned in constraints → hand off to software-architect
• Pricing/packaging implications → hand off to pricing skill
• UI/UX flows need detailed design → hand off to ux-design or ui-design

When handing off, tell the user which skill to invoke and what context to carry over.

Reference Knowledge Base

For deep background on spec writing methodology, anti-patterns, depth calibration frameworks, and cross-functional alignment principles, read:

→ references/spec-writing-guide.md

Consult this reference when:

• You need to explain WHY a certain section matters to the user
• The user asks about spec writing best practices or theory
• You're running an audit and need to justify a recommendation
• The user asks about depth calibration (how much spec is enough)