Write Spec

# Write Spec

> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).

Write a feature specification or product requirements document (PRD).

## Usage

``` /write-spec $ARGUMENTS ```

## Workflow

### 1. Understand the Feature

Ask the user what they want to spec. Accept any of: - A feature name ("SSO support") - A problem statement ("Enterprise customers keep asking for centralized auth") - A user request ("Users want to export their data as CSV") - A vague idea ("We should do something about onboarding drop-off")

### 2. Gather Context

Ask the user for the following. Be conversational — do not dump all questions at once. Ask the most important ones first and fill in gaps as you go:

- **User problem**: What problem does this solve? Who experiences it? - **Target users**: Which user segment(s) does this serve? - **Success metrics**: How will we know this worked? - **Constraints**: Technical constraints, timeline, regulatory requirements, dependencies - **Prior art**: Has this been attempted before? Are there existing solutions?

### 3. Pull Context from Connected Tools

If **~~project tracker** is connected: - Search for related tickets, epics, or features - Pull in any existing requirements or acceptance criteria - Identify dependencies on other work items

If **~~knowledge base** is connected: - Search for related research documents, prior specs, or design docs - Pull in relevant user research findings - Find related meeting notes or decision records

If **~~design** is connected: - Pull related mockups, wireframes, or design explorations - Search for design system components relevant to the feature

If these tools are not connected, work entirely from what the user provides. Do not ask the user to connect tools — just proceed with available information.

### 4. Generate the PRD

Produce a structured PRD with these sections. See **PRD Structure** below for detailed guidance on what each section should contain.

- **Problem Statement**: The user problem, who is affected, and impact of not solving it (2-3 sentences) - **Goals**: 3-5 specific, measurable outcomes tied to user or business metrics - **Non-Goals**: 3-5 things explicitly out of scope, with brief rationale for each - **User Stories**: Standard format ("As a [user type], I want [capability] so that [benefit]"), grouped by persona - **Requirements**: Categorized as Must-Have (P0), Nice-to-Have (P1), and Future Considerations (P2), each with acceptance criteria - **Success Metrics**: Leading indicators (change quickly) and lagging indicators (change over time), with specific targets - **Open Questions**: Unresolved questions tagged with who needs to answer (engineering, design, legal, data) - **Timeline Considerations**: Hard deadlines, dependencies, and phasing

### 5. Review and Iterate

After generating the PRD: - Ask the user if any sections need adjustment - Offer to expand on specific sections - Offer to create follow-up artifacts (design brief, engineering ticket breakdown, stakeholder pitch)

## PRD Structure

### Problem Statement - Describe the user problem in 2-3 sentences - Who experiences this problem and how often - What is the cost of not solving it (user pain, business impact, competitive risk) - Ground this in evidence: user research, support data, metrics, or customer feedback

### Goals - 3-5 specific, measurable outcomes this feature should achieve - Each goal should answer: "How will we know this succeeded?" - Distinguish between user goals (what users get) and business goals (what the company gets) - Goals should be outcomes, not outputs ("reduce time to first value by 50%" not "build onboarding wizard")

### Non-Goals - 3-5 things this feature explicitly will NOT do - Adjacent capabilities that are out of scope for this version - For each non-goal, briefly explain why it is out of scope (not enough impact, too complex, separate initiative, premature) - Non-goals prevent scope creep during implementation and set expectations with stakeholders

### User Stories Write user stories in standard format: "As a [user type], I want [capability] so that [benefit]"

Guidelines: - The user type should be specific enough to be meaningful ("enterprise admin" not just "user") - The capability should describe what they want to accomplish, not how - The benefit should explain the "why" — what value does this deliver - Include edge cases: error states, empty states, boundary conditions - Include different user types if the feature serves multiple personas - Order by priority — most important stories first

Example: - "As a team admin, I want to configure SSO for my organization so that my team members can log in with their corporate credentials" - "As a team member, I want to be automatically redirected to my company's SSO login so that I do not need to remember a separate password" - "As a team admin, I want to see which members have logged in via SSO so that I can verify th