| name | product-spec |
| description | Use when starting a new feature, product, or project — before any architecture or code, to define what to build and why |
Product Specification
Overview
Transform a vague idea into an actionable product spec with user stories, acceptance criteria, and success metrics. This is the first step before any engineering work.
Core principle: If you can't explain what the user does and why they care, you're not ready to code.
When to Use
- Starting a new product or feature
- User says "build X" without detailed requirements
- Before invoking
system-design or any scaffold skill
- When requirements are ambiguous or incomplete
Spec Structure
1. Problem Statement
What problem are we solving? Who has this problem? How do they currently solve it?
## Problem
[Who] struggles with [what] because [why].
Currently they [workaround], which causes [pain].
Ask these questions before writing:
- Who is the user? (persona, not "everyone")
- What's the trigger? (when do they need this?)
- What's the current workaround? (proves the problem exists)
- What happens if we don't build this? (priority check)
2. Solution Overview
One paragraph. What are we building and how does it solve the problem?
## Solution
Build [what] that allows [who] to [do what], resulting in [outcome].
3. User Stories
## User Stories
### Must Have (P0)
- As a [user], I want to [action] so that [benefit]
- AC: Given [context], when [action], then [result]
- AC: Given [context], when [edge case], then [graceful handling]
### Should Have (P1)
- As a [user], I want to [action] so that [benefit]
### Nice to Have (P2)
- As a [user], I want to [action] so that [benefit]
Rules for good user stories:
- Written from user's perspective, not developer's
- Each has measurable acceptance criteria
- P0 = launch blocker, P1 = fast follow, P2 = backlog
- If you can't write AC, the story is too vague — break it down
4. Scope & Non-Goals
## Scope
What's IN this version:
- Feature A
- Feature B
What's explicitly OUT:
- Feature C (future consideration)
- Feature D (different problem)
Non-goals are as important as goals. They prevent scope creep and keep the agent focused.
5. Success Metrics
## Success Metrics
- [Metric]: [Target] (e.g., "User activation: 40% of signups complete onboarding")
- [Metric]: [Target] (e.g., "API latency: p95 < 200ms")
- [Metric]: [Target] (e.g., "Error rate: < 0.1%")
Every feature should have at least one user-facing metric and one technical metric.
6. Technical Constraints
## Constraints
- Stack: [Go/Python/React]
- Auth: [JWT/OAuth/API key]
- Data: [estimated volume, growth rate]
- Integrations: [external services]
- Compliance: [GDPR, SOC2, etc.]
7. Open Questions
## Open Questions
- [ ] How do we handle [edge case]?
- [ ] What's the migration path for existing users?
- [ ] Do we need admin tooling for this?
Don't pretend you have all the answers. Surface unknowns early.
Quick Reference: Story Quality Check
| Bad | Good |
|---|
| "User can manage data" | "User can export last 30 days of transactions as CSV" |
| "System should be fast" | "Search returns results in < 200ms for 95th percentile" |
| "Handle errors gracefully" | "When payment fails, show retry button with error reason" |
| "Admin dashboard" | "Admin can view daily active users and revenue by plan tier" |
| No acceptance criteria | Given/When/Then for each story |
Anti-Patterns
- Solution-first thinking — describing implementation before understanding the problem
- Developer stories — "As a developer, I want a REST API" is not a user story
- Scope creep in P0 — if everything is P0, nothing is P0
- Vague acceptance criteria — "works correctly" is not testable
- Missing non-goals — leads to unbounded scope
Chains
- Next: Invoke
system-design for architecture decisions
- Then: Invoke
superpowers:writing-plans to create implementation plan
- Then: Invoke scaffold skills (
go-scaffold, py-scaffold, react-scaffold)
