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/orspecs/ - 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:
- Mark todo
in_progress - Research OR ask question
- Write findings immediately to interview log
- Expand todos for: new areas revealed, follow-up questions, dependencies discovered
- Update spec file (replace
[TBD]markers) - Mark todo
completed - 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.
-
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.
-
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
-
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 |
-
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.
-
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
-
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
-
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:
-
Implementer: Read each requirement. Could you code it without guessing? If you'd think "I'll ask about X later" → X is underspecified.
-
Tester: For each behavior, can you write a test? If inputs/outputs/conditions are unclear → underspecified.
-
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 |