Spec

Turn a vague idea into a buildable specification through a short, structured interview.

Announce at start: "I'm using the spec skill to help you define this."

Workflow

Interview → Synthesize → Draft → Review → Save

1. Interview — ask structured questions to understand the idea
2. Synthesize — identify scope, constraints, and open questions
3. Draft — write a SPEC.md covering all dimensions
4. Review — walk through the spec with the user, revise until approved
5. Save — write the final spec to disk

Interview

Ask questions one at a time. Prefer multiple-choice when possible. Keep it to 5-8 questions total — infer the rest from context.

Question sequence (adapt to context):

1. What is this? — one-sentence description in the user's words
2. Who is it for? — target user or audience (multiple-choice if obvious candidates exist)
3. What's the trigger? — when/why does someone reach for this?
4. What does success look like? — concrete outcome, not metrics
5. What's the scope? — MVP vs full vision (multiple-choice: minimal / moderate / ambitious)
6. What exists already? — prior art, constraints, systems it must integrate with
7. What's explicitly out of scope? — things that might seem related but aren't part of this
8. Any hard constraints? — tech stack, timeline, platform, compliance, etc.

Rules:

• One question per message. Never batch questions.
• If the user's answer implies the next question's answer, skip it.
• If something is ambiguous, ask a follow-up before moving on.
• Mirror the user's language — don't introduce jargon they didn't use.

Synthesis checkpoint

Before drafting, summarize what you've learned in 3-5 bullets and ask: "Does this capture it? Anything I'm missing or got wrong?"

Only proceed to drafting after the user confirms.

Spec Document Format

Write the spec as a markdown document with these sections. Scale each section to the complexity of the idea — a simple feature gets a few sentences per section, not paragraphs.

# [Feature/Product Name]

## Problem
What problem does this solve? Why does it matter?

## Solution
What are we building? One-paragraph description.

## Users
Who uses this and what's their context?

## Requirements
### Must have
- [ ] ...

### Should have
- [ ] ...

### Won't have (this version)
- [ ] ...

## Design
How it works at a high level. Architecture, key flows, data model —
whatever is relevant. Use diagrams if they clarify.

## Open questions
Unresolved decisions that need input before or during implementation.

## Out of scope
Explicitly excluded to prevent scope creep.

Principles:

• Requirements are concrete and testable, not vague ("fast" → "responds in <200ms")
• "Won't have" is just as important as "Must have"
• Open questions are honest — don't paper over unknowns
• Keep it short enough that someone will actually read it

Saving the spec

Save to: SPEC.md in the project root, unless the user specifies a different location.

If a SPEC.md already exists, ask whether to replace or save alongside it (e.g., SPEC-<feature-name>.md).

After the spec

Present the saved file path and ask what the user wants to do next. Do NOT automatically invoke implementation skills — the user decides the next step.