Writes product specifications through collaborative interview with web research. Use when planning, gathering requirements, designing new features, or creating a spec/PRD.
---
name: spec
description: 'Writes product specifications through collaborative interview with web research. Use when planning, gathering requirements, designing new features, or creating a spec/PRD.'
argument-hint: 'list | revise {spec} | [product idea]'
model: opus
---
**Argument:** $ARGUMENTS
| Command | Behavior |
| --- | --- |
| `/spec list` | List all specs with id, name, status, created date |
| `/spec {idea}` | Create new spec through collaborative interview |
| `/spec revise {spec}` | Save spec and go straight to review with codebase exploration |
---
### List Mode
If `$ARGUMENTS` is `list`:
1. List `.otto/specs/*.md`
2. For each spec, read frontmatter (id, name, status, created_date)
3. Display as table:
```plaintext
| Name | ID | Status | Created |
|------|-----|--------|---------|
| Design Skill | design-skill-a1b2 | approved | 2026-01-28 |
```
4. If no specs found: "No specs found. Run `/spec {idea}` to create one."
5. Stop here — do not continue to interview workflow.
---
### Revise Mode
If `$ARGUMENTS` starts with `revise`:
**Spec Content:** Everything after `revise ` in $ARGUMENTS
If no spec content provided, ask: "Provide the spec content to save. The first line should be the product name."
Parse the provided content:
- **Name:** First line of the spec content
- **Body:** Everything after the first line
### 1. Gather Context
**Analyze codebase:**
- Use Glob to find relevant files
- Use Read to understand current architecture
- Use Grep to search for related patterns
- Note patterns and design decisions for the review
### 2. Draft Spec
Map the provided content to this template structure (mark missing sections as `[TBD]`):
**Product Requirements:**
- **Overview** - What and why, problem being solved
- **Goals / Non-Goals** - Explicit scope boundaries
- **User Stories** - User-facing behavior
**Technical Design:**
- **Architecture** - System design, component relationships
- **Detailed Design** - Implementation approach, key algorithms
- **API / Interface** - Public interfaces, contracts
- **Data Model** - Schema, storage, state
**Planning:**
- **Future Considerations** - Deferred features, extensibility
- **Open Questions** - Unresolved decisions marked as `[TBD: reason]`
### 3. Save Draft
Generate unique ID from product name:
```bash
name=$(echo "$NAME" | head -1)
slug="${name,,}" # Convert to lowercase
slug="${slug// /-}" # Replace spaces with hyphens
slug="${slug:0:30}" # Truncate to 30 characters
hash=$(sha1sum <<< "$name$(date +%s%N)" 2>/dev/null || shasum <<< "$name$(date +%s%N)")
hash="${hash:0:4}"
id="${slug}-${hash}"
mkdir -p .otto/specs
```
Write to `.otto/specs/{id}.md`:
```yaml
---
id: {id}
name: {Name}
status: draft
created_date: {YYYY-MM-DD}
description: {one-line summary of the spec}
---
{spec content mapped to template structure}
```
### 4. Clarify Ambiguities
If any sections are marked `[TBD]` or contain ambiguous requirements:
Use `AskUserQuestion` to resolve each ambiguity before proceeding to review. For each unclear item:
- Present what's missing or unclear
- Offer 2-3 options if applicable
- Update the spec file with the user's answers
Skip this step if the spec is complete with no `[TBD]` markers.
### 5. Review Spec
Launch `technical-product-manager` subagent with Task tool:
**Handoff to technical-product-manager:**
- Spec path: `.otto/specs/{id}.md`
- Spec ID: `{id}`
- Codebase context: Include relevant patterns and architecture discovered in step 1
The subagent reads the spec, reviews for completeness, consistency, feasibility, ambiguity, and technical correctness. Returns prioritized findings (P0-P2) with specific sections, issues, and suggestions.
Wait for review to complete.
### 6. Interview User on Findings
If no findings, skip to step 7.
For each finding (highest priority first):
1. Present the finding with its priority level
2. If suggestion is clear: `AskUserQuestion` with "Accept", "Reject", "Modify"
3. If alternatives exist: `AskUserQuestion` with the options
4. If accepted: Update the spec file with the change
5. If rejected: Skip to next finding
6. If modify: Apply user's modified version
After processing all findings, update the spec file with changes.
### 7. Approval
**Output the full spec** as rendered markdown so the user can review it inline.
**Use `AskUserQuestion`** with options:
- "Approve"
- "Request changes"
- "Open in editor" — run `open .otto/specs/{id}.md`, then ask again
**After each revision:** Output the full updated spec as rendered markdown before asking for approval again. Revise until approved.
On approval, update `status: draft` to `status: approved` in the file.
Report: "Spec approved and saved to `.otto/specs/{id}.md`"
### 8. Next Steps
Offer task generation:
> "Run `/task {name}` to generate implementation tasks."
---
### Create Mode
**Product Idea:** $ARGUMENTS
If no argument provided, ask: "What would you like to build?"
### 1. Gather Context
**Check for existing specs:**
```bash
ls .otto/specs/*.md 2>/dev/null
```
**Ask about reference projects:**
> "Are there any reference projects or examples I should look at for inspiration?"
If provided, explore the reference project(s) to understand their approach.
**Analyze codebase:**
- Use Glob to find relevant files
- Use Read to understand current architecture
- Use Grep to search for related patterns
- Note patterns and design decisions to reference during interview
### 2. Research Best Practices
Use `WebSearch` to find and `WebFetch` to read:
- Industry best practices for the product type
- Common pitfalls and recommendations
- How popular projects solve similar problems
- Documentation and API references
**For visual research** (competitor products, reference implementations):
- Use browser automation (`skills/otto/lib/browser`) to navigate sites and capture screenshots
- Save screenshots to `.otto/research/`
### 3. Interview
Use `AskUserQuestion` to gather requirements. For each decision point:
- Present 2-3 options
- Mark one as "(Recommended)" based on research
- Include pros/cons and what research suggests
**Topics to cover:**
- Core requirements and constraints
- Key architectural decisions
- Scope boundaries (what's in, what's out)
- Edge cases
### 4. Draft Spec
Write a spec covering:
**Product Requirements:**
- **Overview** - What and why, problem being solved
- **Goals / Non-Goals** - Explicit scope boundaries
- **User Stories** - User-facing behavior
**Technical Design:**
- **Architecture** - System design, component relationships
- **Detailed Design** - Implementation approach, key algorithms
- **API / Interface** - Public interfaces, contracts
- **Data Model** - Schema, storage, state
**Planning:**
- **Future Considerations** - Deferred features, extensibility
- **Open Questions** - Unresolved decisions marked as `[TBD: reason]`
### 5. Save Draft
Generate unique ID from product idea:
```bash
slug="${ARGUMENTS,,}" # Convert to lowercase
slug="${slug// /-}" # Replace spaces with hyphens
slug="${slug:0:30}" # Truncate to 30 characters
hash=$(sha1sum <<< "$ARGUMENTS$(date +%s%N)" 2>/dev/null || shasum <<< "$ARGUMENTS$(date +%s%N)")
hash="${hash:0:4}"
id="${slug}-${hash}"
mkdir -p .otto/specs
```
Write to `.otto/specs/{id}.md`:
```yaml
---
id: {id}
name: {Product Idea}
status: draft
created_date: {YYYY-MM-DD}
description: {one-line summary of the spec}
---
{spec content}
```
### 6. Review Spec
Launch `technical-product-manager` subagent with Task tool:
**Handoff to technical-product-manager:**
- Spec path: `.otto/specs/{id}.md`
- Spec ID: `{id}`
The subagent reads the spec, reviews for completeness, consistency, feasibility, ambiguity, and technical correctness. Returns prioritized findings (P0-P2) with specific sections, issues, and suggestions.
Wait for review to complete.
### 7. Interview User on Findings
If no findings, skip to step 8.
For each finding (highest priority first):
1. Present the finding with its priority level
2. If suggestion is clear: `AskUserQuestion` with "Accept", "Reject", "Modify"
3. If alternatives exist: `AskUserQuestion` with the options
4. If accepted: Update the spec file with the change
5. If rejected: Skip to next finding
6. If modify: Apply user's modified version
After processing all findings, update the spec file with changes.
### 8. Approval
**Output the full spec** as rendered markdown so the user can review it inline.
**Use `AskUserQuestion`** with options:
- "Approve"
- "Request changes"
- "Open in editor" — run `open .otto/specs/{id}.md`, then ask again
**After each revision:** Output the full updated spec as rendered markdown before asking for approval again. Revise until approved.
On approval, update `status: draft` to `status: approved` in the file.
Report: "Spec approved and saved to `.otto/specs/{id}.md`"
### 9. Next Steps
Offer task generation:
> "Run `/task {name}` to generate implementation tasks."
