Write Spec

1---2name: write-spec3description: Write a feature spec or PRD from a problem statement or feature idea. Use when turning a vague idea or user request into a structured document, scoping a feature with goals and non-goals, defining success metrics and acceptance criteria, or breaking a big ask into a phased spec.4argument-hint: "<feature or problem statement>"5---6 7# Write Spec8 9> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).10 11Write a feature specification or product requirements document (PRD).12 13## Usage14 15```16/write-spec $ARGUMENTS17```18 19## Workflow20 21### 1. Understand the Feature22 23Ask the user what they want to spec. Accept any of:24- A feature name ("SSO support")25- A problem statement ("Enterprise customers keep asking for centralized auth")26- A user request ("Users want to export their data as CSV")27- A vague idea ("We should do something about onboarding drop-off")28 29### 2. Gather Context30 31Ask 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:32 33- **User problem**: What problem does this solve? Who experiences it?34- **Target users**: Which user segment(s) does this serve?35- **Success metrics**: How will we know this worked?36- **Constraints**: Technical constraints, timeline, regulatory requirements, dependencies37- **Prior art**: Has this been attempted before? Are there existing solutions?38 39### 3. Pull Context from Connected Tools40 41If **~~project tracker** is connected:42- Search for related tickets, epics, or features43- Pull in any existing requirements or acceptance criteria44- Identify dependencies on other work items45 46If **~~knowledge base** is connected:47- Search for related research documents, prior specs, or design docs48- Pull in relevant user research findings49- Find related meeting notes or decision records50 51If **~~design** is connected:52- Pull related mockups, wireframes, or design explorations53- Search for design system components relevant to the feature54 55If 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.56 57### 4. Generate the PRD58 59Produce a structured PRD with these sections. See **PRD Structure** below for detailed guidance on what each section should contain.60 61- **Problem Statement**: The user problem, who is affected, and impact of not solving it (2-3 sentences)62- **Goals**: 3-5 specific, measurable outcomes tied to user or business metrics63- **Non-Goals**: 3-5 things explicitly out of scope, with brief rationale for each64- **User Stories**: Standard format ("As a [user type], I want [capability] so that [benefit]"), grouped by persona65- **Requirements**: Categorized as Must-Have (P0), Nice-to-Have (P1), and Future Considerations (P2), each with acceptance criteria66- **Success Metrics**: Leading indicators (change quickly) and lagging indicators (change over time), with specific targets67- **Open Questions**: Unresolved questions tagged with who needs to answer (engineering, design, legal, data)68- **Timeline Considerations**: Hard deadlines, dependencies, and phasing69 70### 5. Review and Iterate71 72After generating the PRD:73- Ask the user if any sections need adjustment74- Offer to expand on specific sections75- Offer to create follow-up artifacts (design brief, engineering ticket breakdown, stakeholder pitch)76 77## PRD Structure78 79### Problem Statement80- Describe the user problem in 2-3 sentences81- Who experiences this problem and how often82- What is the cost of not solving it (user pain, business impact, competitive risk)83- Ground this in evidence: user research, support data, metrics, or customer feedback84 85### Goals86- 3-5 specific, measurable outcomes this feature should achieve87- Each goal should answer: "How will we know this succeeded?"88- Distinguish between user goals (what users get) and business goals (what the company gets)89- Goals should be outcomes, not outputs ("reduce time to first value by 50%" not "build onboarding wizard")90 91### Non-Goals92- 3-5 things this feature explicitly will NOT do93- Adjacent capabilities that are out of scope for this version94- For each non-goal, briefly explain why it is out of scope (not enough impact, too complex, separate initiative, premature)95- Non-goals prevent scope creep during implementation and set expectations with stakeholders96 97### User Stories98Write user stories in standard format: "As a [user type], I want [capability] so that [benefit]"99 100Guidelines:101- The user type should be specific enough to be meaningful ("enterprise admin" not just "user")102- The capability should describe what they want to accomplish, not how103- The benefit should explain the "why" — what value does this deliver104- Include edge cases: error states, empty states, boundary conditions105- Include different user types if the feature serves multiple personas106- Order by priority — most important stories first107 108Example:109- "As a team admin, I want to configure SSO for my organization so that my team members can log in with their corporate credentials"110- "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"111- "As a team admin, I want to see which members have logged in via SSO so that I can verify the rollout is working"112 113### Requirements114 115**Must-Have (P0)**: The feature cannot ship without these. These represent the minimum viable version of the feature. Ask: "If we cut this, does the feature still solve the core problem?" If no, it is P0.116 117**Nice-to-Have (P1)**: Significantly improves the experience but the core use case works without them. These often become fast follow-ups after launch.118 119**Future Considerations (P2)**: Explicitly out of scope for v1 but we want to design in a way that supports them later. Documenting these prevents accidental architectural decisions that make them hard later.120 121For each requirement:122- Write a clear, unambiguous description of the expected behavior123- Include acceptance criteria (see below)124- Note any technical considerations or constraints125- Flag dependencies on other teams or systems126 127### Open Questions128- Questions that need answers before or during implementation129- Tag each with who should answer (engineering, design, legal, data, stakeholder)130- Distinguish between blocking questions (must answer before starting) and non-blocking (can resolve during implementation)131 132### Timeline Considerations133- Hard deadlines (contractual commitments, events, compliance dates)134- Dependencies on other teams' work or releases135- Suggested phasing if the feature is too large for one release136 137## User Story Writing138 139Good user stories are:140- **Independent**: Can be developed and delivered on their own141- **Negotiable**: Details can be discussed, the story is not a contract142- **Valuable**: Delivers value to the user (not just the team)143- **Estimable**: The team can roughly estimate the effort144- **Small**: Can be completed in one sprint/iteration145- **Testable**: There is a clear way to verify it works146 147### Common Mistakes in User Stories148- Too vague: "As a user, I want the product to be faster" — what specifically should be faster?149- Solution-prescriptive: "As a user, I want a dropdown menu" — describe the need, not the UI widget150- No benefit: "As a user, I want to click a button" — why? What does it accomplish?151- Too large: "As a user, I want to manage my team" — break this into specific capabilities152- Internal focus: "As the engineering team, we want to refactor the database" — this is a task, not a user story153 154## Requirements Categorization155 156### MoSCoW Framework157- **Must have**: Without these, the feature is not viable. Non-negotiable.158- **Should have**: Important but not critical for launch. High-priority fast follows.159- **Could have**: Desirable if time permits. Will not delay delivery if cut.160- **Won't have (this time)**: Explicitly out of scope. May revisit in future versions.161 162### Tips for Categorization163- Be ruthless about P0s. The tighter the must-have list, the faster you ship and learn.164- If everything is P0, nothing is P0. Challenge every must-have: "Would we really not ship without this?"165- P1s should be things you are confident you will build soon, not a wish list.166- P2s are architectural insurance — they guide design decisions even though you are not building them now.167 168## Success Metrics Definition169 170### Leading Indicators171Metrics that change quickly after launch (days to weeks):172- **Adoption rate**: % of eligible users who try the feature173- **Activation rate**: % of users who complete the core action174- **Task completion rate**: % of users who successfully accomplish their goal175- **Time to complete**: How long the core workflow takes176- **Error rate**: How often users encounter errors or dead ends177- **Feature usage frequency**: How often users return to use the feature178 179### Lagging Indicators180Metrics that take time to develop (weeks to months):181- **Retention impact**: Does this feature improve user retention?182- **Revenue impact**: Does this drive upgrades, expansion, or new revenue?183- **NPS / satisfaction change**: Does this improve how users feel about the product?184- **Support ticket reduction**: Does this reduce support load?185- **Competitive win rate**: Does this help win more deals?186 187### Setting Targets188- Targets should be specific: "50% adoption within 30 days" not "high adoption"189- Base targets on comparable features, industry benchmarks, or explicit hypotheses190- Set a "success" threshold and a "stretch" target191- Define the measurement method: what tool, what query, what time window192- Specify when you will evaluate: 1 week, 1 month, 1 quarter post-launch193 194## Acceptance Criteria195 196Write acceptance criteria in Given/When/Then format or as a checklist:197 198**Given/When/Then**:199- Given [precondition or context]200- When [action the user takes]201- Then [expected outcome]202 203Example:204- Given the admin has configured SSO for their organization205- When a team member visits the login page206- Then they are automatically redirected to the organization's SSO provider207 208**Checklist format**:209- [ ] Admin can enter SSO provider URL in organization settings210- [ ] Team members see "Log in with SSO" button on login page211- [ ] SSO login creates a new account if one does not exist212- [ ] SSO login links to existing account if email matches213- [ ] Failed SSO attempts show a clear error message214 215### Tips for Acceptance Criteria216- Cover the happy path, error cases, and edge cases217- Be specific about the expected behavior, not the implementation218- Include what should NOT happen (negative test cases)219- Each criterion should be independently testable220- Avoid ambiguous words: "fast", "user-friendly", "intuitive" — define what these mean concretely221 222## Scope Management223 224### Recognizing Scope Creep225Scope creep happens when:226- Requirements keep getting added after the spec is approved227- "Small" additions accumulate into a significantly larger project228- The team is building features no user asked for ("while we're at it...")229- The launch date keeps moving without explicit re-scoping230- Stakeholders add requirements without removing anything231 232### Preventing Scope Creep233- Write explicit non-goals in every spec234- Require that any scope addition comes with a scope removal or timeline extension235- Separate "v1" from "v2" clearly in the spec236- Review the spec against the original problem statement — does everything serve it?237- Time-box investigations: "If we cannot figure out X in 2 days, we cut it"238- Create a "parking lot" for good ideas that are not in scope239 240## Output Format241 242Use markdown with clear headers. Keep the document scannable — busy stakeholders should be able to read just the headers and bold text to get the gist.243 244## Tips245 246- Be opinionated about scope. It is better to have a tight, well-defined spec than an expansive vague one.247- If the user's idea is too big for one spec, suggest breaking it into phases and spec the first phase.248- Success metrics should be specific and measurable, not vague ("improve user experience").249- Non-goals are as important as goals. They prevent scope creep during implementation.250- Open questions should be genuinely open — do not include questions you can answer from context.