Write Spec

Write Spec

If you see unfamiliar placeholders or need to check which tools are connected, see 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 the rollout is working"

Requirements

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.

Nice-to-Have (P1): Significantly improves the experience but the core use case works without them. These often become fast follow-ups after launch.

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.

For each requirement:

• Write a clear, unambiguous description of the expected behavior

• Include acceptance criteria (see below)

• Note any technical considerations or constraints

• Flag dependencies on other teams or systems

Open Questions

• Questions that need answers before or during implementation

• Tag each with who should answer (engineering, design, legal, data, stakeholder)

• Distinguish between blocking questions (must answer before starting) and non-blocking (can resolve during implementation)

Timeline Considerations

• Hard deadlines (contractual commitments, events, compliance dates)

• Dependencies on other teams' work or releases

• Suggested phasing if the feature is too large for one release

User Story Writing

Good user stories are:

• Independent: Can be developed and delivered on their own

• Negotiable: Details can be discussed, the story is not a contract

• Valuable: Delivers value to the user (not just the team)

• Estimable: The team can roughly estimate the effort

• Small: Can be completed in one sprint/iteration

• Testable: There is a clear way to verify it works

Common Mistakes in User Stories

• Too vague: "As a user, I want the product to be faster" — what specifically should be faster?

• Solution-prescriptive: "As a user, I want a dropdown menu" — describe the need, not the UI widget

• No benefit: "As a user, I want to click a button" — why? What does it accomplish?

• Too large: "As a user, I want to manage my team" — break this into specific capabilities

• Internal focus: "As the engineering team, we want to refactor the database" — this is a task, not a user story

Requirements Categorization

MoSCoW Framework

• Must have: Without these, the feature is not viable. Non-negotiable.

• Should have: Important but not critical for launch. High-priority fast follows.

• Could have: Desirable if time permits. Will not delay delivery if cut.

• Won't have (this time): Explicitly out of scope. May revisit in future versions.

Tips for Categorization

• Be ruthless about P0s. The tighter the must-have list, the faster you ship and learn.

• If everything is P0, nothing is P0. Challenge every must-have: "Would we really not ship without this?"

• P1s should be things you are confident you will build soon, not a wish list.

• P2s are architectural insurance — they guide design decisions even though you are not building them now.

Success Metrics Definition

Leading Indicators

Metrics that change quickly after launch (days to weeks):

• Adoption rate: % of eligible users who try the feature

• Activation rate: % of users who complete the core action

• Task completion rate: % of users who successfully accomplish their goal

• Time to complete: How long the core workflow takes

• Error rate: How often users encounter errors or dead ends

• Feature usage frequency: How often users return to use the feature

Lagging Indicators

Metrics that take time to develop (weeks to months):

• Retention impact: Does this feature improve user retention?

• Revenue impact: Does this drive upgrades, expansion, or new revenue?

• NPS / satisfaction change: Does this improve how users feel about the product?

• Support ticket reduction: Does this reduce support load?

• Competitive win rate: Does this help win more deals?

Setting Targets

• Targets should be specific: "50% adoption within 30 days" not "high adoption"

• Base targets on comparable features, industry benchmarks, or explicit hypotheses

• Set a "success" threshold and a "stretch" target

• Define the measurement method: what tool, what query, what time window

• Specify when you will evaluate: 1 week, 1 month, 1 quarter post-launch

Acceptance Criteria

Write acceptance criteria in Given/When/Then format or as a checklist:

Given/When/Then:

• Given [precondition or context]

• When [action the user takes]

• Then [expected outcome]

Example:

• Given the admin has configured SSO for their organization

• When a team member visits the login page

• Then they are automatically redirected to the organization's SSO provider

Checklist format:

• [ ] Admin can enter SSO provider URL in organization settings

• [ ] Team members see "Log in with SSO" button on login page

• [ ] SSO login creates a new account if one does not exist

• [ ] SSO login links to existing account if email matches

• [ ] Failed SSO attempts show a clear error message

Tips for Acceptance Criteria

• Cover the happy path, error cases, and edge cases

• Be specific about the expected behavior, not the implementation

• Include what should NOT happen (negative test cases)

• Each criterion should be independently testable

• Avoid ambiguous words: "fast", "user-friendly", "intuitive" — define what these mean concretely

Scope Management

Recognizing Scope Creep

Scope creep happens when:

• Requirements keep getting added after the spec is approved

• "Small" additions accumulate into a significantly larger project

• The team is building features no user asked for ("while we're at it...")

• The launch date keeps moving without explicit re-scoping

• Stakeholders add requirements without removing anything

Preventing Scope Creep

• Write explicit non-goals in every spec

• Require that any scope addition comes with a scope removal or timeline extension

• Separate "v1" from "v2" clearly in the spec

• Review the spec against the original problem statement — does everything serve it?

• Time-box investigations: "If we cannot figure out X in 2 days, we cut it"

• Create a "parking lot" for good ideas that are not in scope

Output Format

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

Tips

• Be opinionated about scope. It is better to have a tight, well-defined spec than an expansive vague one.

• If the user's idea is too big for one spec, suggest breaking it into phases and spec the first phase.

• Success metrics should be specific and measurable, not vague ("improve user experience").

• Non-goals are as important as goals. They prevent scope creep during implementation.

• Open questions should be genuinely open — do not include questions you can answer from context.