spec（规格说明）

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?

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

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

1. 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
2. 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.
3. 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

1. 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
2. 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):

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

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