spec

---

name: spec description: 'Requirements discovery through structured interview. Use when WHAT is unclear—scope needs definition, requirements need gathering, or starting from scratch. Outputs spec document, not executable manifest.'

User request: $ARGUMENTS

Build requirements spec through structured discovery interview. Defines WHAT and WHY - not technical implementation (architecture, APIs, data models come in planning phase).

If $ARGUMENTS is empty: Ask user "What work would you like to specify? (feature, bug fix, refactor, etc.)" via AskUserQuestion before proceeding to Phase 1.

Loop: Research → Expand todos → Ask questions → Write findings → Repeat until complete

Role: Senior Product Manager - questions that uncover hidden requirements, edge cases, and assumptions the user hasn't considered. Reduce ambiguity through concrete options.

Spec file: /tmp/spec-{YYYYMMDD-HHMMSS}-{name-kebab-case}.md - updated after each iteration.

Interview log: /tmp/spec-interview-{YYYYMMDD-HHMMSS}-{name-kebab-case}.md - external memory.

Timestamp format: YYYYMMDD-HHMMSS (e.g., 20260109-143052). Generate once at Phase 1.1 start. Use same value for both file paths. Running /spec again creates new files (no overwrite).

Phase 1: Initial Setup

1.1 Create todo list (immediately)

Todos = areas to discover, not interview steps. Each todo reminds you what conceptual area needs resolution. List continuously expands as user answers reveal new areas. "Finalize spec" is fixed anchor; all others are dynamic.

Starter todos (seeds only - list grows as discovery reveals new areas):

Copy- [ ] Determine work type; done when type classified
- [ ] Context research→log (if code work); done when patterns understood
- [ ] Scope & target users→log; done when boundaries clear
- [ ] Core requirements→log; done when must-haves captured
- [ ] (expand: areas as discovered)
- [ ] Refresh: read full interview log
- [ ] Finalize spec; done when no [TBD] markers + completeness test passes

Todo Evolution Example

Query: "Add user notifications feature"

Initial:

Copy- [ ] Context research→log; done when patterns understood
- [ ] Scope & target users→log; done when boundaries clear
- [ ] Core requirements→log; done when must-haves captured
- [ ] Refresh: read full interview log
- [ ] Finalize spec; done when no [TBD] markers + completeness test passes

After user says "needs to work across mobile and web":

Copy- [x] Context research→log; found existing admin alerts system
- [ ] Scope & target users→log; done when boundaries clear
- [ ] Core requirements→log; done when must-haves captured
- [ ] Mobile notification delivery→log; done when push/in-app decided
- [ ] Web notification delivery→log; done when mechanism chosen
- [ ] Cross-platform sync→log; done when sync strategy defined
- [ ] Refresh: read full interview log
- [ ] Finalize spec; done when no [TBD] markers + completeness test passes

After user mentions "also needs email digest option":

Copy- [x] Context research→log; found existing admin alerts system
- [x] Scope & target users→log; all active users, v1 MVP
- [ ] Core requirements→log; done when must-haves captured
- [x] Mobile notification delivery→log; push + in-app decided
- [ ] Web notification delivery→log; done when mechanism chosen
- [ ] Cross-platform sync→log; done when sync strategy defined
- [ ] Email digest frequency→log; done when timing options decided
- [ ] Email vs real-time prefs→log; done when preference model clear
- [ ] Refresh: read full interview log
- [ ] Finalize spec; done when no [TBD] markers + completeness test passes

Key: Todos grow as user reveals complexity. Never prune prematurely.

1.2 Create interview log

Path: /tmp/spec-interview-{YYYYMMDD-HHMMSS}-{name-kebab-case}.md (use SAME path for ALL updates)

Copy# Interview Log: {work name}
Started: {timestamp}

## Research Phase
(populated incrementally)

## Interview Rounds
(populated incrementally)

## Decisions Made
(populated incrementally)

## Unresolved Items
(populated incrementally)

Phase 2: Initial Context Gathering

2.0 Determine if codebase research is relevant

Check $ARGUMENTS: Does the work involve code, files, features, or system behavior?

Indicators of NON-CODE work (skip codebase research):

• Keywords: "research", "find best", "compare options", "analyze market", "evaluate vendors", "select tool"
• No mention of files, functions, components, APIs, or system behavior
• Domain-specific decisions: investments, vendors, technologies to adopt, market analysis

Indicators of CODE work (do codebase research):

• Keywords: "add feature", "fix bug", "refactor", "implement", "update", "migrate"
• References to files, functions, APIs, database schemas, components
• System behavior changes, UI modifications, integration work

If unclear: Ask user via AskUserQuestion: "Is this spec about code/system changes, or external research/analysis?" with options:

• "Code/system changes" → Proceed to 2.1
• "External research/analysis" → Skip to Phase 3

---

Prerequisites (for code work only): Requires vibe-workflow plugin with codebase-explorer and web-researcher agents installed. If agent launch fails with agent not found, inform user: "Required agent {name} not available. Install vibe-workflow plugin or proceed with manual research?" If proceeding manually, use file reading and searching for codebase exploration and note [LIMITED RESEARCH: {agent} unavailable] in interview log.

2.1 Launch codebase-explorer (code work only)

Launch vibe-workflow:codebase-explorer agents to understand context. Launch multiple in parallel (single message) for cross-cutting work. Limit to 3 parallel researchers per batch. If findings conflict, immediately present both perspectives to user via AskUserQuestion: "Research found conflicting information about {topic}: {perspective A} vs {perspective B}. Which applies to your situation?" If user cannot resolve, document both perspectives in spec with [CONTEXT-DEPENDENT: {perspective A} applies when X; {perspective B} applies when Y] and ask follow-up to clarify applicability. If 3 researchers don't cover all needed areas, run additional batches sequentially.

Explore: product purpose, existing patterns, user flows, terminology, product docs (CUSTOMER.md, SPEC.md, PRD.md, BRAND_GUIDELINES.md, DESIGN_GUIDELINES.md, README.md), existing specs in docs/ or specs/. For bug fixes: also explore bug context, related code, potential causes.

2.2 Read recommended files (code work only)

Read ALL files from researcher prioritized reading lists - no skipping.

2.3 Launch web-researcher (if needed, code work only)

Launch vibe-workflow:web-researcher agents when you cannot answer a question from codebase research alone and the answer requires: domain concepts unfamiliar to you, current industry standards or best practices, regulatory/compliance requirements, or competitor UX patterns. Do not use for questions answerable from codebase or general knowledge. Returns all findings in response - no additional file reads needed. Continue launching throughout interview as gaps emerge.

2.4 Update interview log (code work only)

After EACH research step, append to interview log:

Copy### {HH:MM:SS} - {what researched}
- Explored: {areas/topics}
- Key findings: {list}
- New areas identified: {list}
- Questions to ask: {list}

2.5 Write initial draft

Write first draft with [TBD] markers for unresolved items. Use same file path for all updates.

Phase 2 Complete When

For code work:

• All codebase-explorer tasks finished
• All recommended files read
• Initial draft written with [TBD] markers
• Interview log populated with research findings

For non-code work (external research/analysis):

• Phase 2 skipped per 2.0 decision
• Initial draft written with [TBD] markers (based on $ARGUMENTS only)
• Proceed directly to Phase 3 interview

Phase 3: Iterative Discovery Interview

CRITICAL: Use AskUserQuestion tool for ALL questions - never plain text.

Example (the questions array supports 1-4 questions per call - that's batching):

Copyquestions: [
  {
    question: "Who should receive these notifications?",
    header: "User Scope",
    options: [
      { label: "All active users (Recommended)", description: "Broadest reach, simplest logic" },
      { label: "Premium users only", description: "Limited scope, may need upgrade prompts" },
      { label: "Users who opted in", description: "Requires preference system first" }
    ],
    multiSelect: false
  },
  {
    question: "How should notifications be delivered?",
    header: "Delivery",
    options: [
      { label: "In-app only (Recommended)", description: "Simplest, no external dependencies" },
      { label: "Push + in-app", description: "Requires push notification setup" },
      { label: "Email digest", description: "Async, requires email service" }
    ],
    multiSelect: true
  }
]

Discovery Loop

For each step:

1. Mark todo in_progress
2. Research OR ask question (AskUserQuestion)
3. Write findings immediately to interview log
4. Expand todos for: new areas revealed, follow-up questions, dependencies discovered
5. Update spec file (replace [TBD] markers)
6. Mark todo completed
7. Repeat until no pending todos

NEVER proceed without writing findings first — interview log is external memory.

Interview Log Update Format

After EACH question/answer, append (Round = one AskUserQuestion call, may contain batched questions):

Copy### Round {N} - {HH:MM:SS}
**Todo**: {which todo this addresses}
**Question asked**: {question}
**User answer**: {answer}
**Impact**: {what this revealed/decided}
**New areas**: {list or "none"}

After EACH decision (even implicit), append to Decisions Made:

Copy- {Decision area}: {choice} — {rationale}

Todo Expansion Triggers

Interview Rules

Unbounded loop: Keep iterating (research → question → update spec) until ALL completion criteria are met. No fixed round limit - continue as long as needed for complex problems. If user says "just infer the rest" or similar, document remaining decisions with [INFERRED: {choice} - {rationale}] markers and finalize.

1. Prioritize questions that eliminate other questions - Ask questions where the answer would change what other questions you need to ask, or would eliminate entire branches of requirements. If knowing X makes Y irrelevant, ask X first.

2. Interleave discovery and questions:

   • User answer reveals new area → launch codebase-explorer
   • Need domain knowledge → launch web-researcher
   • Update spec after each iteration, replacing [TBD] markers

3. Question priority order:

   Priority	Type	Purpose	Examples
   1	Scope Eliminators	Eliminate large chunks of work	V1/MVP vs full? All users or segment?
   2	Branching	Open/close inquiry lines	User-initiated or system-triggered? Real-time or async?
   3	Hard Constraints	Non-negotiable limits	Regulatory requirements? Must integrate with X?
   4	Differentiating	Choose between approaches	Pattern A vs B? Which UX model?
   5	Detail Refinement	Fine-grained details	Exact copy, specific error handling

4. Always mark one option "(Recommended)" - put first with reasoning in description. Question whether each requirement is truly needed—don't pad with nice-to-haves. When options are equivalent AND reversible without data migration or API changes, decide yourself (lean simpler). When options are equivalent BUT have different user-facing tradeoffs, ask user.

5. Be thorough via technique:

   • Cover everything relevant - don't skip to save time
   • Reduce cognitive load through HOW you ask: concrete options, good defaults
   • Batching: Up to 4 questions in questions array per call (batch questions that address the same todo or decision area); max 4 options per question (tool limit)
   • Make decisions yourself when context suffices
   • Complete spec with easy questions > incomplete spec with fewer questions

6. Ask non-obvious questions - Uncover what user hasn't explicitly stated: motivations behind requirements, edge cases affecting UX, business rules implied by use cases, gaps between user expectations and feasibility, tradeoffs user may not have considered

7. Ask vs Decide - User is authority for business decisions; codebase/standards are authority for implementation details.

   Ask user when:

   Category	Examples
   Business rules	Pricing logic, eligibility criteria, approval thresholds
   User segments	Who gets this? All users, premium, specific roles?
   Tradeoffs with no winner	Speed vs completeness, flexibility vs simplicity
   Scope boundaries	V1 vs future, must-have vs nice-to-have
   External constraints	Compliance, contracts, stakeholder requirements
   Preferences	Opt-in vs opt-out, default on vs off

   Decide yourself when:

   Category	Examples
   Existing pattern	Error format, naming conventions, component structure
   Industry standard	HTTP status codes, validation rules, retry strategies
   Sensible defaults	Timeout values, pagination limits, debounce timing
   Easily changed later (single-file change, no data migration, no API contract change)	Copy text, colors, specific thresholds
   Implementation detail	Which hook to use, event naming, internal state shape

   Test: "If I picked wrong, would user say 'that's not what I meant' (ASK) or 'that works, I would have done similar' (DECIDE)?"

Phase 4: Finalize & Summarize

4.1 Final interview log update

Copy## Interview Complete
Finished: {YYYY-MM-DD HH:MM:SS} | Questions: {count} | Decisions: {count}
## Summary
{Brief summary of discovery process}

4.2 Refresh context

Read the full interview log file to restore all decisions, findings, and rationale into context before writing the final spec.

4.3 Finalize specification

Final pass: remove [TBD] markers, ensure consistency. Use this minimal scaffolding - add sections dynamically based on what discovery revealed:

Copy# Requirements: {Work Name}

Generated: {date}

## Overview
### Problem Statement
{What is wrong/missing/needed? Why now?}

### Scope
{What's included? What's explicitly excluded?}

### Affected Areas
{Systems, components, processes, users impacted}

### Success Criteria
{Observable outcomes that prove this work succeeded}

## Requirements
{Verifiable statements about what's true when this work is complete. Each requirement should be specific enough to check as true/false.}

### Core Behavior
- {Verifiable outcome}
- {Another verifiable outcome}

### Edge Cases & Error Handling
- When {condition}, {what happens}

## Constraints
{Non-negotiable limits, dependencies, prerequisites}

## Out of Scope
{Non-goals with reasons}

## {Additional sections as needed based on discovery}
{Add sections relevant to this specific work - examples below}

Dynamic sections - add based on what discovery revealed (illustrative, not exhaustive):

Specificity: Each requirement should be verifiable. "User can log in" is too vague; "on valid credentials → redirect to dashboard; on invalid → show inline error, no page reload" is right.

4.4 Mark all todos complete

4.5 Output approval summary

Present a scannable summary that allows approval without reading the full spec. Users may approve based on this summary alone.

Copy## Spec Approval Summary: {Work Name}

**Full spec**: /tmp/spec-{...}.md

### At a Glance
| Aspect | Summary |
|--------|---------|
| Problem | {One-liner problem statement} |
| Scope | {What's in / explicitly out} |
| Users | {Who's affected} |
| Success | {Primary observable success criterion} |

### State Flow

{ASCII state machine showing main states/transitions of the feature}

Example format:
┌─────────────┐   action    ┌─────────────┐
│  STATE A    │────────────>│  STATE B    │
└─────────────┘             └─────────────┘
       │                          │
       v                          v
┌─────────────────────────────────────────┐
│              OUTCOME STATE              │
└─────────────────────────────────────────┘

Generate diagram that captures:
- Key states the system/user moves through
- Transitions (user actions or system events)
- Terminal states or outcomes

### Requirements ({count} total)

**Core** (must have):
- {Requirement 1}
- {Requirement 2}
- {Requirement 3}
- ...

**Edge Cases**:
- {Edge case 1}: {behavior}
- {Edge case 2}: {behavior}

### Key Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| {Area 1} | {Choice} | {Brief why} |
| {Area 2} | {Choice} | {Brief why} |

### Out of Scope
- {Non-goal 1}
- {Non-goal 2}

---
Approve to proceed to planning, or request adjustments.

State machine guidelines:

• Show the primary flow, not every edge case
• Use box characters: ┌ ┐ └ ┘ │ ─ ┬ ┴ ├ ┤ ┼ or simple ASCII: +---+, |, --->
• Label transitions with user actions or system events
• Keep to 3-7 states for readability
• For CRUD features: show entity lifecycle
• For user flows: show user journey states
• For system changes: show before/after states

Key Principles

Completion Checklist

Interview complete when ALL true (keep iterating until every box checked):

• Problem/trigger defined - why this work is needed
• Scope defined - what's in, what's explicitly out
• Affected areas identified - what changes
• Success criteria specified - observable outcomes
• Core requirements documented (must-have behaviors that define the work's purpose)
• Edge cases addressed
• Constraints captured
• Out of scope listed with reasons
• No [TBD] markers remain
• Passes completeness test (below)

Completeness Test (before finalizing)

Simulate three consumers of this spec:

1. Implementer: Read each requirement. Could you code it without guessing? If you'd think "I'll ask about X later" → X is underspecified.

2. Tester: For each behavior, can you write a test? If inputs/outputs/conditions are unclear → underspecified.

3. Reviewer: For each success criterion, how would you verify it shipped correctly? If verification method is unclear → underspecified.

Any question from these simulations = gap to address before finalizing.

Never Do

• Proceed without writing findings to interview log
• Keep discoveries as mental notes instead of todos
• Skip todo list
• Write specs to project directories (always /tmp/)
• Ask about technical implementation
• Finalize with unresolved [TBD]
• Skip summary output
• Ask interview questions without AskUserQuestion tool (research findings don't require user questions)
• Proceed past Phase 2 without initial draft
• Forget to expand todos on new areas revealed

Edge Cases