spec

name	spec
description	Build requirements specification through structured discovery interview. Use when defining scope, gathering requirements, or specifying WHAT work should accomplish - features, bugs, refactors, infrastructure, migrations, performance, documentation, or any other work type. Triggers: spec, requirements, define scope, what to build.
metadata	{"short-description":"Interactive requirements builder"}

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.)" before proceeding.

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 (update_plan 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):

- [ ] Initial context research
- [ ] Scope & target users
- [ ] Core requirements
- [ ] (expand continuously as answers reveal new areas)
- [ ] Read full interview log (context refresh before output)
- [ ] Finalize spec

Todo Evolution Example

Query: "Add user notifications feature"

Initial:

- [ ] Initial context research
- [ ] Scope & target users
- [ ] Core requirements
- [ ] Read full interview log (context refresh before output)
- [ ] Finalize spec

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

- [x] Initial context research → found existing notification system for admin alerts
- [ ] Scope & target users
- [ ] Core requirements
- [ ] Mobile notification delivery (push vs in-app)
- [ ] Web notification delivery (browser vs in-app)
- [ ] Cross-platform sync behavior
- [ ] Read full interview log (context refresh before output)
- [ ] Finalize spec

After user mentions "also needs email digest option":

- [x] Initial context research
- [x] Scope & target users → all active users, v1 MVP
- [ ] Core requirements
- [x] Mobile notification delivery → push + in-app
- [ ] Web notification delivery
- [ ] Cross-platform sync behavior
- [ ] Email digest frequency options
- [ ] Email vs real-time preferences
- [ ] Read full interview log (context refresh before output)
- [ ] Finalize spec

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)

# 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?

If $ARGUMENTS...	Then...
References code files, functions, components, features, bugs, refactors, or system behavior	Proceed to 2.1 (codebase research)
Is about external research, analysis, comparison, or domain decisions (e.g., "research best X", "compare options", "find optimal Y")	SKIP to Phase 3 (interview)

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: "Is this spec about code/system changes, or external research/analysis?"

2.1 Research codebase context (code work only)

Explore the codebase to understand context before asking questions. Use file search and code reading to find:

• 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

Read ALL relevant files discovered - no skipping.

2.3 Web research (if needed)

Use web search 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.

2.4 Update interview log

After EACH research step, append to interview log:

### {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 research 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

Memento Loop

For each step:

1. Mark todo in_progress
2. Research OR ask question
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 question, may contain batched questions):

### 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:

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

Todo Expansion Triggers

Discovery Reveals	Add Todos For
New affected area	Requirements for that area
Integration need	Integration constraints
Compliance/regulatory	Compliance requirements
Multiple scenarios/flows	Each scenario's behavior
Error conditions	Error handling approach
Performance concern	Performance constraints/metrics
Existing dependency	Dependency investigation
Rollback/recovery need	Recovery strategy
Data preservation need	Data integrity requirements

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 → research codebase
   • Need domain knowledge → use web search
   • 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 provide a recommended option - put first with reasoning. 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: Group related questions together (questions that address the same todo or decision area)
   • 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

## 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:

# 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):

Discovery Reveals	Add Section
User-facing behavior	Screens/states (empty, loading, success, error), interactions, accessibility
API/technical interface	Contract (inputs/outputs/errors), integration points, versioning
Bug context	Current vs expected, reproduction steps, verification criteria
Refactoring	Current/target structure, invariants (what must NOT change)
Infrastructure	Rollback plan, monitoring, failure modes
Migration	Data preservation, rollback, cutover strategy
Performance	Current baseline, target metrics, measurement method
Data changes	Schema, validation rules, retention
Security & privacy	Auth/authz requirements, data sensitivity, audit needs
User preferences	Configurable options, defaults, persistence
External integrations	Third-party services, rate limits, fallbacks
Observability	Analytics events, logging, success/error metrics

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.

## 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

Principle	Rule
Memento style	Write findings BEFORE next question (interview log = external memory)
Todo-driven	Every discovery needing follow-up → todo (no mental notes)
WHAT not HOW	Requirements only - no architecture, APIs, data models, code patterns. Self-check: if thinking "how to implement," refocus on "what should happen/change"
Observable outcomes	Focus on what changes when complete. Ask "what is different after?" not "how does it work internally?" Edge cases = system/business impact
Dynamic structure	Spec sections emerge from discovery. No fixed template beyond core scaffolding. Add sections as needed to fully specify the WHAT
Complete coverage	Spec covers EVERYTHING implementer needs: behavior, UX, data, errors, edge cases, accessibility - whatever the work touches. If they'd have to guess, it's underspecified
Comprehensive spec, minimal questions	Spec covers everything implementer needs. Ask questions only when: (1) answer isn't inferable from codebase/context, (2) wrong guess would require changing 3+ files or redoing more than one day of work, (3) it's a business decision only user can make. Skip questions you can answer via research
No open questions	Resolve everything during interview - no TBDs in final spec
Question requirements	Don't accept requirements at face value. Ask "is this truly needed for v1?" Don't pad specs with nice-to-haves
Reduce cognitive load	Recommended option first, multi-choice over free-text. Free-text only when: options are infinite/unpredictable, asking for specific values (names, numbers), or user needs to describe own context. User accepting defaults should yield solid result
Incremental updates	Update interview log after EACH step (not at end)

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 (3+ 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
• Proceed past Phase 2 without initial draft
• Forget to expand todos on new areas revealed

Edge Cases

Scenario	Action
User declines to answer	Note [USER SKIPPED: reason], flag in summary
Insufficient research	Ask user directly, note uncertainty
Contradictory requirements	Surface conflict before proceeding
User corrects earlier decision	Update spec, log correction with reason, check if other requirements affected
Interview interrupted	Spec saved; add [INCOMPLETE] at top. To resume: provide existing spec file path as argument
Resume interrupted spec	Read provided spec file. If file not found or not a valid spec (missing required sections like Overview, Requirements), inform user: "Could not resume from {path}: {reason}. Start fresh?" If valid, look for matching interview log at same timestamp, scan for [TBD] and [INCOMPLETE] markers, present status to user and ask "Continue from {last incomplete area}?"
"Just build it"	Push back with 2-3 critical questions (questions where guessing wrong = significant rework). If declined, document assumptions clearly