spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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).

用户请求：$ARGUMENTS

通过结构化探索式访谈构建需求规格说明书。仅明确目标（WHAT）与原因（WHY）——不涉及技术实现细节（架构、API、数据模型属于规划阶段内容）。

若$ARGUMENTS为空：在继续之前询问用户“您需要明确哪类工作的需求？（如功能开发、Bug修复、代码重构等）”

循环流程：调研 → 扩展待办事项 → 提出问题 → 记录发现 → 重复直至完成

角色定位：资深产品经理——提出能挖掘隐藏需求、边缘场景及用户未考虑到的假设的问题。通过具体选项减少歧义。

规格文件路径：

/tmp/spec-{YYYYMMDD-HHMMSS}-{name-kebab-case}.md

——每次迭代后更新。

访谈日志路径：

/tmp/spec-interview-{YYYYMMDD-HHMMSS}-{name-kebab-case}.md

——外部记忆存储。

时间戳格式：

YYYYMMDD-HHMMSS

（示例：

20260109-143052

）。在1.1阶段开始时生成一次，两个文件路径使用同一时间戳。再次运行$spec命令会创建新文件（不会覆盖原有文件）。

Phase 1: Initial Setup

第一阶段：初始设置

1.1 Create todo list (update_plan immediately)

1.1 创建待办事项列表（立即更新计划）

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.

用户请求：“添加用户通知功能”

初始待办事项：

- [ ] 初始背景调研
- [ ] 范围与目标用户
- [ ] 核心需求
- [ ] 通读访谈日志（输出前刷新上下文）
- [ ] 最终确定规格

用户说明“需支持移动端和网页端”后：

- [x] 初始背景调研 → 发现已有的管理员告警通知系统
- [ ] 范围与目标用户
- [ ] 核心需求
- [ ] 移动端通知推送方式（推送通知 vs 应用内通知）
- [ ] 网页端通知推送方式（浏览器通知 vs 应用内通知）
- [ ] 跨平台同步行为
- [ ] 通读访谈日志（输出前刷新上下文）
- [ ] 最终确定规格

用户提及“还需支持邮件摘要选项”后：

- [x] 初始背景调研
- [x] 范围与目标用户 → 所有活跃用户，v1版本为MVP
- [ ] 核心需求
- [x] 移动端通知推送方式 → 推送通知 + 应用内通知
- [ ] 网页端通知推送方式
- [ ] 跨平台同步行为
- [ ] 邮件摘要频率选项
- [ ] 邮件通知与实时通知偏好设置
- [ ] 通读访谈日志（输出前刷新上下文）
- [ ] 最终确定规格

关键原则：待办事项随用户揭示的复杂度增长。切勿过早删减。

1.2 Create interview log

1.2 创建访谈日志

Path:

/tmp/spec-interview-{YYYYMMDD-HHMMSS}-{name-kebab-case}.md

(use SAME path for ALL updates)

markdown

undefined

路径：

/tmp/spec-interview-{YYYYMMDD-HHMMSS}-{name-kebab-case}.md

（所有更新均使用同一路径）

markdown

undefined

Interview Log: {work name}

访谈日志：{工作名称}

Started: {timestamp}

开始时间：{时间戳}

Research Phase

调研阶段

(populated incrementally)

（逐步填充内容）

Interview Rounds

访谈轮次

(populated incrementally)

（逐步填充内容）

Decisions Made

已做出的决策

(populated incrementally)

（逐步填充内容）

Unresolved Items

未解决事项

(populated incrementally)

undefined

（逐步填充内容）

undefined

Phase 2: Initial Context Gathering

第二阶段：初始背景收集

2.0 Determine if codebase research is relevant

2.0 判断是否需要进行代码库调研

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

检查$ARGUMENTS：该工作是否涉及代码、文件、功能或系统行为？

若$ARGUMENTS...	则...
提及代码文件、函数、组件、功能、Bug、重构或系统行为	进入2.1（代码库调研）
涉及外部调研、分析、对比或领域决策（例如“研究最佳X方案”、“对比选项”、“寻找最优Y”）	跳过至第三阶段（访谈）

非代码工作的判断指标（跳过代码库调研）：

关键词：“研究”、“寻找最佳”、“对比选项”、“市场分析”、“评估供应商”、“选择工具”
未提及文件、函数、组件、API或系统行为
领域特定决策：投资、供应商、拟采用的技术、市场分析

代码工作的判断指标（需进行代码库调研）：

关键词：“添加功能”、“修复Bug”、“重构”、“实现”、“更新”、“迁移”
提及文件、函数、API、数据库 schema、组件
系统行为变更、UI修改、集成工作

若无法明确：询问用户：“此规格是针对代码/系统变更，还是外部调研/分析？”

2.1 Research codebase context (code work only)

2.1 调研代码库上下文（仅代码工作）

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

在提出问题前，先探索代码库以了解上下文。通过文件搜索和代码阅读找到以下内容：

产品用途、现有模式、用户流程、术语
产品文档（CUSTOMER.md、SPEC.md、PRD.md、BRAND_GUIDELINES.md、DESIGN_GUIDELINES.md、README.md）
```
docs/
```
或
```
specs/
```
目录下的现有规格文档
若为Bug修复：还需探索Bug背景、相关代码、潜在原因

2.2 Read recommended files

2.2 阅读推荐文件

Read ALL relevant files discovered - no skipping.

阅读所有发现的相关文件——不得跳过。

2.3 Web research (if needed)

2.3 网络调研（如有需要）

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.

当无法通过代码库调研回答问题，且答案需要以下内容时，使用网络搜索：不熟悉的领域概念、当前行业标准或最佳实践、法规/合规要求、竞品UX模式。不得用于可通过代码库或通用知识回答的问题。

2.4 Update interview log

2.4 更新访谈日志

After EACH research step, append to interview log:

markdown

undefined

每次调研步骤完成后，将内容追加到访谈日志：

markdown

undefined

{HH:MM:SS} - {what researched}

{HH:MM:SS} - {调研内容}

Explored: {areas/topics}
Key findings: {list}
New areas identified: {list}
Questions to ask: {list}

undefined

探索领域：{领域/主题}
关键发现：{列表}
识别的新领域：{列表}
需提出的问题：{列表}

undefined

2.5 Write initial draft

2.5 撰写初始草稿

Write first draft with

[TBD]

markers for unresolved items. Use same file path for all updates.

撰写第一版草稿，对未解决的项使用

[TBD]

标记。所有更新均使用同一文件路径。

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

代码工作：

所有代码库调研任务完成
所有推荐文件已阅读
已撰写带有
```
[TBD]
```
标记的初始草稿
访谈日志已填充调研发现

非代码工作（外部调研/分析）：

根据2.0的决策跳过第二阶段
仅基于$ARGUMENTS撰写带有
```
[TBD]
```
标记的初始草稿
直接进入第三阶段访谈

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.

每个步骤：

将待办事项标记为
```
in_progress
```
调研或提出问题
立即将发现写入访谈日志
扩展待办事项：涵盖新揭示的领域、后续问题、发现的依赖项
更新规格文件（替换
```
[TBD]
```
标记）
将待办事项标记为
```
completed
```
重复直至无待办事项

切勿在未先记录发现的情况下继续——访谈日志是外部记忆。

Interview Log Update Format

访谈日志更新格式

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

markdown

undefined

每次问答后追加内容（一轮 = 一个问题，可包含批量问题）：

markdown

undefined

Round {N} - {HH:MM:SS}

第{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:

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

待办事项：{对应的待办项} 提出的问题：{问题内容} 用户回答：{回答内容} 影响：{揭示/确定的内容} 新领域：{列表或“无”}


每次做出决策（即使是隐含决策）后，追加到“已做出的决策”部分：

```markdown
- {决策领域}：{选择} — {理由}

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)?"

无边界循环：持续迭代（调研 → 提问 → 更新规格）直至所有完成标准满足。无固定轮次限制——复杂问题需持续多久就持续多久。若用户表示“自行推断剩余内容”或类似表述，需使用

[INFERRED: {选择} - {理由}]

标记记录剩余决策，然后最终确定规格。

优先提出能减少后续问题的问题——提出那些答案会改变后续需提问题，或能消除整个需求分支的问题。如果了解X会使Y变得无关紧要，先问X。
交替进行探索与提问:
- 用户回答揭示新领域 → 调研代码库
- 需要领域知识 → 使用网络搜索
- 每次迭代后更新规格文件，替换
```
[TBD]
```
  标记

问题优先级顺序:

优先级	类型	目的	示例
1	范围排除类	排除大块工作内容	V1/MVP 还是完整版本？面向所有用户还是特定群体？
2	分支类	开启/关闭调查方向	用户触发还是系统触发？实时还是异步？
3	硬约束类	不可协商的限制	法规要求？必须与X集成？
4	差异化类	在多种方案中选择	模式A还是B？采用哪种UX模型？
5	细节优化类	细粒度细节	确切文案、特定错误处理

始终提供推荐选项——将推荐选项放在首位并说明理由。质疑每个需求是否真的必要——不要添加锦上添花的内容。当选项等效且无需数据迁移或API变更即可逆转时，自行决策（倾向于更简单的方案）。当选项等效但对用户有不同权衡时，询问用户。
通过技巧确保全面性:
- 覆盖所有相关内容——不要为了节省时间而跳过
- 通过提问方式降低认知负荷：提供具体选项、合理默认值
- 批量提问：将相关问题分组（针对同一待办项或决策领域的问题）
- 当上下文足够时自行做出决策
- 优先完成包含简单问题的完整规格，而非包含更少问题的不完整规格
提出非显而易见的问题——挖掘用户未明确说明的内容：需求背后的动机、影响UX的边缘场景、用例隐含的业务规则、用户期望与可行性之间的差距、用户可能未考虑到的权衡

提问 vs 自行决策——用户是业务决策的权威；代码库/标准是实现细节的权威。

需询问用户的情况:

类别	示例
业务规则	定价逻辑、资格标准、审批阈值
用户群体	面向谁？所有用户、付费用户、特定角色？
无明确最优解的权衡	速度 vs 完整性、灵活性 vs 简洁性
范围边界	V1 vs 未来版本、必须具备 vs 锦上添花
外部约束	合规性、合同、利益相关者要求
偏好设置	选择加入 vs 选择退出、默认开启 vs 关闭

可自行决策的情况:

类别	示例
现有模式	错误格式、命名规范、组件结构
行业标准	HTTP状态码、验证规则、重试策略
合理默认值	超时时间、分页限制、防抖时机
后续可轻松修改（单文件变更、无需数据迁移、无需修改API契约）	文案、颜色、特定阈值
实现细节	使用哪个Hook、事件命名、内部状态结构

测试方法：“如果我决策错误，用户会说‘这不是我想要的’（需提问）还是‘这样可以，我也会这么做’（可自行决策）？”

Phase 4: Finalize & Summarize

第四阶段：最终确定与总结

4.1 Final interview log update

4.1 最终更新访谈日志

markdown

undefined

markdown

undefined

Interview Complete

访谈完成

Finished: {YYYY-MM-DD HH:MM:SS} | Questions: {count} | Decisions: {count}

结束时间：{YYYY-MM-DD HH:MM:SS} | 问题数量：{count} | 决策数量：{count}

Summary

总结

{Brief summary of discovery process}

undefined

{探索过程的简要总结}

undefined

4.2 Refresh context

4.2 刷新上下文

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

通读完整的访谈日志文件，在撰写最终规格前，将所有决策、发现和理由恢复到上下文当中。

4.3 Finalize specification

4.3 最终确定规格说明书

Final pass: remove

[TBD]

markers, ensure consistency. Use this minimal scaffolding - add sections dynamically based on what discovery revealed:

markdown

undefined

最终检查：移除

[TBD]

标记，确保一致性。使用以下最小框架——根据探索过程揭示的内容动态添加章节：

markdown

undefined

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.

{添加与该工作相关的章节——以下为示例}


**动态章节**——根据探索过程揭示的内容添加（示例非 exhaustive）：

| 探索揭示内容 | 添加章节 |
|-------------------|-------------|
| 用户可见行为 | 页面/状态（空状态、加载中、成功、错误）、交互、可访问性 |
| API/技术接口 | 契约（输入/输出/错误）、集成点、版本控制 |
| Bug背景 | 当前状态 vs 预期状态、复现步骤、验证标准 |
| 重构 | 当前/目标结构、不变量（必须保持不变的内容） |
| 基础设施 | 回滚计划、监控、故障模式 |
| 迁移 | 数据保留、回滚、切换策略 |
| 性能 | 当前基准、目标指标、测量方法 |
| 数据变更 | Schema、验证规则、保留策略 |
| 安全与隐私 | 认证/授权要求、数据敏感度、审计需求 |
| 用户偏好 | 可配置选项、默认值、持久化 |
| 外部集成 | 第三方服务、速率限制、降级方案 |
| 可观测性 | 分析事件、日志、成功/错误指标 |

**具体性**：每个需求应可验证。“用户可以登录”过于模糊；“输入有效凭据 → 重定向至仪表盘；输入无效凭据 → 显示内联错误，不刷新页面”才是正确的表述。

4.4 Mark all todos complete

4.4 标记所有待办事项为已完成

4.5 Output approval summary

4.5 输出审批摘要

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

undefined

提供一个易于扫描的摘要，使用户无需阅读完整规格即可审批。用户可仅基于此摘要进行审批。

undefined

Spec Approval Summary: {Work Name}

规格审批摘要：{工作名称}

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

完整规格：/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

{ASCII状态机，展示功能的主要状态/流转}

示例格式： ┌─────────────┐ 操作 ┌─────────────┐ │ 状态A │────────────>│ 状态B │ └─────────────┘ └─────────────┘ │ │ v v ┌─────────────────────────────────────────┐ │ 结果状态 │ └─────────────────────────────────────────┘

生成的图应包含：

系统/用户经历的关键状态
流转（用户操作或系统事件）
终端状态或结果

Requirements ({count} total)

需求（共{count}项）

Core (must have):

{Requirement 1}
{Requirement 2}
{Requirement 3}
...

Edge Cases:

{Edge case 1}: {behavior}
{Edge case 2}: {behavior}

核心需求（必须具备）：

{需求1}
{需求2}
{需求3}
...

边缘场景：

{边缘场景1}：{行为}
{边缘场景2}：{行为}

Key Decisions

关键决策

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

决策领域	选择	理由
{领域1}	{选择}	{简要理由}
{领域2}	{选择}	{简要理由}

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

{非目标1}
{非目标2}

请审批以进入规划阶段，或提出调整要求。


**状态机指南**:
- 展示主要流程，而非所有边缘场景
- 使用方框字符：`┌ ┐ └ ┘ │ ─ ┬ ┴ ├ ┤ ┼` 或简单ASCII：`+---+`、`|`、`--->`
- 为流转标注用户操作或系统事件
- 保持3-7个状态以确保可读性
- 对于CRUD功能：展示实体生命周期
- 对于用户流程：展示用户旅程状态
- 对于系统变更：展示变更前后状态

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)

原则	规则
记忆式工作流	在下一个问题前先记录发现（访谈日志 = 外部记忆）
待办事项驱动	所有需跟进的探索内容 → 待办事项（不依赖记忆）
只关注目标（WHAT）而非实现方式（HOW）	仅记录需求——不涉及架构、API、数据模型、代码模式。自我检查：若思考“如何实现”，需重新聚焦于“应发生/变更什么”
可观察结果	关注完成后发生的变化。问“完成后有什么不同？”而非“内部如何工作？”边缘场景 = 系统/业务影响
动态结构	规格章节从探索过程中产生。除核心框架外无固定模板。根据需要添加章节以完整明确目标
全面覆盖	规格需包含实现者所需的所有内容：行为、UX、数据、错误、边缘场景、可访问性——无论工作涉及什么。如果实现者需要猜测，说明规格不够明确
全面规格，最少问题	规格需包含实现者所需的所有内容。仅在以下情况提问：(1) 无法从代码库/上下文推断答案，(2) 错误猜测会导致修改3个以上文件或重做超过一天的工作，(3) 这是只有用户才能做出的业务决策。跳过可通过调研回答的问题
无未解决问题	在访谈过程中解决所有问题——最终规格中无 `[TBD]`
质疑需求	不要表面接受需求。问“这对v1版本真的必要吗？”不要在规格中添加锦上添花的内容
降低认知负荷	优先提供推荐选项，使用多选而非自由文本。仅在以下情况使用自由文本：选项无限/不可预测、询问具体值（名称、数字）、或用户需要描述自身上下文。用户接受默认值应能得到可靠结果
增量更新	每次步骤后更新访谈日志（而非在最后统一更新）

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)

访谈完成需满足以下所有条件（持续迭代直至所有项勾选）：

已定义问题/触发原因——为什么需要这项工作
已定义范围——包含什么，明确排除什么
已识别受影响领域——哪些内容会变更
已明确成功标准——可观察的结果
已记录核心需求（3项以上定义工作目的的必须具备的行为）
已处理边缘场景
已捕获约束条件
已列出范围外内容及理由
最终规格中无
```
[TBD]
```
标记
通过完整性测试（如下）

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.

模拟三类规格使用者：

实现者：阅读每个需求。是否无需猜测即可编码？如果会想“稍后我要问X” → X的规格不够明确。
测试者：针对每个行为，能否编写测试用例？如果输入/输出/条件不明确 → 规格不够明确。
审核者：针对每个成功标准，如何验证工作已正确交付？如果验证方式不明确 → 规格不够明确。

任何模拟中出现的问题 = 最终确定前需填补的空白。

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

未将发现写入访谈日志就继续
将发现记在脑中而非添加为待办事项
跳过待办事项列表
将规格写入项目目录（始终使用
```
/tmp/
```
）
询问技术实现细节
最终规格中存在未解决的
```
[TBD]
```
跳过摘要输出
未撰写初始草稿就进入第二阶段之后的步骤
发现新领域时未扩展待办事项

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

场景	操作
用户拒绝回答	记录 `[USER SKIPPED: 原因]` ，在摘要中标记
调研信息不足	直接询问用户，记录不确定性
需求矛盾	在继续前指出冲突
用户更正之前的决策	更新规格，记录更正及理由，检查是否影响其他需求
访谈中断	保存规格；在顶部添加 `[INCOMPLETE]` 标记。恢复方式：将现有规格文件路径作为参数提供
恢复中断的规格	读取提供的规格文件。如果文件未找到或不是有效规格（缺少概述、需求等必填章节），告知用户：“无法从{路径}恢复：{原因}。是否重新开始？”如果有效，查找同一时间戳对应的访谈日志，扫描 `[TBD]` 和 `[INCOMPLETE]` 标记，向用户展示状态并询问“从{最后未完成的领域}继续？”
“直接构建即可”	提出2-3个关键问题（错误猜测会导致大量返工的问题）。如果用户仍拒绝回答，清晰记录假设

undefined