Spec Builder

Transform vague ideas into concrete, actionable spec documents through structured interviews.

Workflow

Phase 1: Gather Initial Context

First, prompt for the idea:

What's the idea you'd like to turn into a spec?
Describe it however it exists in your head right now - it can be vague.

Then ask background questions to calibrate the interview depth:

AskUserQuestion:
1. "What's your background?"
   - Technical (developer/engineer)
   - Semi-technical (PM, designer, technical founder)
   - Non-technical (business, creative, general user)

2. "What's the goal for this spec?"
   - MVP/prototype to test the idea
   - Full product spec for development
   - Pitch document for stakeholders
   - Personal reference to clarify my thinking

Phase 2: Deep Interview

Conduct the interview using AskUserQuestion with batched questions (2-4 related questions per batch).

Rules:

• Never assume - if something is ambiguous, ask
• Provide sensible default options for every question
• Add "(Recommended)" to the best default option
• Anticipate needs the user hasn't considered
• Adapt question depth based on user's technical level

Question calibration by user background:

Interview domains to cover (adapt based on product type):

For software products:

• Core functionality (what does it do?)
• User types and permissions
• Key user flows (step by step)
• Data model (what entities exist?)
• UI/UX preferences (style, layout, interactions)
• Integrations (external services, APIs)
• Edge cases and error handling
• Security and privacy requirements
• Platform (web, mobile, desktop, CLI)

For physical products:

• Core functionality
• Materials and form factor
• User interaction (how do you use it?)
• Manufacturing considerations
• Safety requirements
• Packaging and delivery

For all products:

• Success criteria (how do we know it works?)
• Constraints (budget, timeline, must-haves)
• Anti-goals (what it explicitly should NOT do)

Example batched question:

AskUserQuestion (batch):
1. "Who are the main users of this product?"
   - Single user type (just me / general public)
   - Two distinct roles (e.g., admin + regular user)
   - Multiple user types (need to define each)

2. "Do users need accounts?"
   - No accounts needed (Recommended for MVP)
   - Simple accounts (email/password)
   - Social login (Google, GitHub, etc.)
   - Enterprise SSO

Phase 3: Draft Review

After covering core questions (~10-15 batches), present a draft outline:

Here's the spec outline based on our conversation so far:

## [Product Name] - Spec Outline

**Overview:** [1-2 sentences]

**Core Features:**
1. [Feature A]
2. [Feature B]
...

**User Types:** [list]

**Key Flows:** [list main workflows]

**Technical Approach:** [high-level decisions]

**Open Questions:** [things still unclear]

---

Does this capture your vision? What's missing or wrong?

Then use AskUserQuestion to get feedback:

1. "How does this outline look?"
   - Looks good, continue with details
   - Missing something important (I'll explain)
   - Some parts are wrong (I'll clarify)
   - Let's pivot direction

Phase 4: Deep Dive

Based on feedback, ask detailed follow-up questions on:

• Unclear areas from the outline
• Edge cases and error states
• Specific UI/UX details
• Technical constraints
• Anything marked as "Open Questions"

Continue until confident all ambiguity is resolved.

Phase 5: Write Spec

Write the final spec to spec-<product-name>.md in the current directory.

Spec format principles:

• Detailed enough for an AI coding agent to implement
• Skimmable for human review (use headers, bullets, tables)
• No vague language - every requirement must be concrete
• Include explicit anti-goals and out-of-scope items
• Write as a standalone document - never mention the interview process or reference "our conversation"

Spec structure (adapt sections based on product type):

# [Product Name] Spec

## Overview
[2-3 sentences: what it is, who it's for, core value prop]

## Goals & Non-Goals

### Goals
- [Concrete goal 1]
- [Concrete goal 2]

### Non-Goals (explicitly out of scope)
- [What this product will NOT do]

## User Types
[Table or list of user types and their permissions/capabilities]

## Core Features

### Feature 1: [Name]
**Purpose:** [Why this feature exists]
**Behavior:**
- [Specific behavior 1]
- [Specific behavior 2]
**UI:** [Description or wireframe reference]

[Repeat for each feature]

## User Flows

### Flow 1: [Name]
1. User does X
2. System responds with Y
3. User sees Z
...

[Repeat for key flows]

## Data Model
[Tables, entities, relationships - for software]
[Components, materials - for physical products]

## Technical Decisions
[Architecture choices, technologies, integrations]
[Skip for non-technical users or physical products]

## Edge Cases & Error Handling
- When X happens, the system should Y
- If Z fails, show error message: "..."

## Open Questions
[Anything that still needs resolution before building]

## Future Considerations
[Ideas mentioned but explicitly deferred]

Key Principles

1. Be thorough - Ask many questions. 10-20 batches is normal for a complex product.
2. Never assume - If two interpretations are possible, ask which one.
3. Provide defaults - Every question should have reasonable options with a recommended choice.
4. Adapt depth - Technical users get technical questions; non-technical users get plain language.
5. Surface unknowns - Ask about things the user probably hasn't considered yet.
6. Stay concrete - The final spec should have zero vague requirements.