Scope

scope —— 把需求拷问清楚

概览

先快速理解项目当前状态与需求规模，然后通过决策树式提问把未决策点拷问清楚。对用户进行不留情面的访谈，直到我们达成共同理解。

硬性关口

阶段 3 确认出口前，不调用实施类 skill，不写代码或执行其他实现动作；此前只允许用户点名的元技能 / 审查技能、必要的只读仓库探索（含 wiki 摘要预检）和 scope 所需的澄清。此关口适用于所有 scope 任务。

流程

阶段 1：判断规模与必要探索

根据预估代码改动量自行判断规模，不问用户：

• 小需求：预估代码改动量足够小，通常只涉及一个局部行为和少量文件，不引入或改变架构、跨模块接口、数据结构、部署或迁移。
• 中大需求：预估代码改动量较大，涉及多个行为或模块，或包含架构、接口、数据、部署、迁移等重大决策；必要探索后仍无法界定改动规模时按中大需求处理，不因尚未探索就直接升级。

所有规模都允许最小充分探索：搜索相关代码和测试，读取最相关的文件，并按需查看历史提交；已掌握足够事实的小需求可跳过重复探索。不要把代码能回答的问题交给用户。docs/wiki/ 存在且有助于定位上下文时，先扫描路径和首行摘要，再按需读取少量候选正文；wiki 不能代替代码事实，也不作为阶段 1 的必要条件。

确定需求规模，并掌握建立阶段 2 的决策账本所需的事实后，阶段 1 完成。

阶段 2：拷问式连续提问

入口

根据当前对话和阶段 1 获得的事实建立内部决策账本，只跟踪需求边界和技术决策；每项标记为“已确认”“待决策”或“不适用”。账本只用于控制访谈和防止遗漏，不直接抄入实施契约或 spec。

若不存在适用的待决策项，不重新发起访谈，直接检查完成条件。

收敛顺序

先收敛需求，再收敛技术落地：

• 需求收敛：明确目标、支持与排除边界、可观察的正常与失败行为，以及必须保持的兼容行为。
• 技术收敛：基于已确认需求做针对性只读探索，只确认影响职责、架构、接口、数据、部署、迁移、安全或兼容性的高阶技术决策；局部实现细节留给 implement。

技术方案与已确认需求冲突时，重新打开对应的需求决策。用户推翻已确认结论时，也重新打开对应项。

核心规则

• 决策树式深挖。每次只选择影响最高的一个待决策项，不重问已确认内容，也不追问“不适用”项；用户回答后更新决策账本，A 的回答决定下一题问 B 还是 B'。
• 每题给推荐答案。让用户审核而不是白板思考。
• 代码库能答的不问用户。
• 不擅自揣测。遇到无法由当前对话或代码事实唯一确定的内容、相互矛盾的结论或多种合理解释时，标记为“待决策”并交由用户决定。
• 优先多选题（A/B/C + 推荐），开放式次之。
• 选项之间空一行，确保每个选项是独立 Markdown 段落。
• 关注目的、约束、成功标准。需求问题不问实现方式；技术问题只问存在实质取舍的落地方案。

完成条件

需求边界和技术决策中的所有适用项均已确认或不适用，且已具备形成设计视图和预估改动面的必要事实后，阶段 2 完成。

阶段 3：总结确认 + 出口选择

入口

只有决策账本中的所有适用项均已确认或不适用，才能进入本阶段。

设计确认

根据阶段 2 已确认的内容，简短呈现双方已经达成一致的目标、需求边界、技术方案，以及理解整体方案所必需的关键结构或流程。

设计呈现只用于暴露理解偏差，不要求达到 spec 的详细度；不展开完整验收证据、预估改动面、文件范围或实施步骤，除非它们会影响已确认决策。

这一轮只做设计确认，不同时给出 A/B 出口。呈现后按以下格式确认：

如有偏差，请直接指出；理解一致时确认继续。

确认以上理解并继续选择执行路径？

用户纠正需求边界或技术方案时，回到阶段 2 重新打开对应决策；仅修正表述时，在本阶段更新后重新呈现。

出口选择

用户确认设计呈现后，按「wiki 落地判断」生成建议，并在同一条消息中按以下格式确认出口和 wiki 目标：

**wiki 更新建议：** <更新 path / 新建 path / 不更新 wiki>

**A. 落 spec** —— 写入 `docs/scope/<日期>-<slug>.md`；批准后交给 implement 规划并执行

**B. 不落 spec** —— 在当前对话中生成实施契约；确认后直接交给 implement 执行，不生成 scope 或 plan 文档；契约只存在于本次对话，会话中断即丢失

**推荐路径：** <A / B>，<简短理由>

下一步走哪条路径？如需调整 wiki 目标，请一并说明。

默认依据阶段 1 的规模判断推荐路径：中大需求推荐 A，小需求推荐 B；有明确理由时可以偏离并说明原因。用户选择优先于推荐；路径与 wiki 目标均确认后，才能进入出口执行。

出口执行

正式契约只在用户选择路径并确认 wiki 目标后生成。以决策账本、当前对话中的已确认结论和代码事实为依据，不把设计呈现当作完整契约来源。

验收由 AI 根据需求边界、技术决策和代码事实推导，不要求用户提供；如果推导过程中发现需要用户决定的实质需求或技术歧义，返回阶段 2。

A. 落 spec

1. 写 spec 文件前调用 git-workflow 的 prepare 阶段。
2. 写 docs/scope/<YYYY-MM-DD>-<slug>.md，按下文模板组织；slug 是根据主题生成的 kebab-case 英文短标题。
3. 按下文清单执行完整自我审查并就地修复。
4. 请用户审阅；审阅与修改期间沿用第 1 步建立的 Git 上下文。用户要求修改时，修改后重新完整自审；如果修改导致 wiki 更新目标变化，先向用户确认新的 wiki 文件。
5. 用户批准后，把 spec 头部状态回写为 > 状态：已批准 <YYYY-MM-DD>，再调用 checkpoint 只处理当前 spec。
6. 调用 implement，传入 source_kind: approved-spec、source: <spec 路径>、已确认的 wiki 目标和 git_state: prepared；implement 生成 plan 后直接执行，不再二次确认计划。

B. 不落 spec

1. 不写 spec 文件；参考下方 spec 模板及通用规则，在对话中生成其精简版，包含目标、决策基线、设计视图（功能设计、技术设计）、预估改动面和验收；只展开本次实施所需内容，关键结构或实现流程按需补充。
2. 按下文清单执行完整自我审查并就地修复。
3. 请用户确认实施契约。
4. 用户确认后调用 implement，传入 source_kind: confirmed-conversation、source: <完整对话契约>、已确认的 wiki 目标和 git_state: unprepared；不生成 docs/scope/ 或 docs/plans/ 文档，由 implement 直接规划并执行。

完成条件

阶段 3 只允许两种出口：已确认对话契约交给 implement，或已批准 spec 交给 implement。

wiki 落地判断

离开 scope、进入 implement 前，必须完成 wiki 落地判断；这个判断不以是否落 spec 为前提。

• 扫描方式：先读 docs/wiki/ 路径和每个 .md 第一行摘要，再按需读取少量候选正文，形成具体且有事实依据的目标建议；不全库读取正文。
• 确认时机：阶段 3 询问是否落 spec 时，同时让用户确认 wiki 目标；把结果作为 implement 输入，后续只同步用户确认过的文件。
• 建议类型：更新 <path>、新建 <path>、不更新 wiki。
• 落 spec：大任务默认建议同步 wiki。可更新已有页面；也可在用户确认后新建最小必要目录或页面。
• 不落 spec：小任务只建议更新已有 wiki；没有匹配页面时不新建，除非用户明确要求沉淀。
• 可写入内容：已确认的架构、约定、术语、稳定流程、模块背景、决策背景。
• 不可写入内容：未确认猜测、一次性任务步骤、执行 checklist、对话过程。

阶段 3 生成建议前必须已有上述摘要扫描和必要候选正文的判断结果；阶段 1 已获取则复用，否则此时补做。没有匹配页面时，小任务默认“不更新 wiki”，中大任务才可建议在用户确认后新建最小必要页面。不要把“建议更新”当成用户已经授权。

wiki 同步是 implement 的第一个实施工作单元，不改变 scope 出口。

spec.md 模板

spec 是 scope 与 implement 之间的设计基线，只保留约束实现或决定验收的结论，不记录访谈过程，也不提前展开 plan。

尖括号内容是字段说明，生成时替换并移除；标注“按需”的章节不适用时省略。

> 由 scope skill 于 <YYYY-MM-DD> 生成
> 状态：待批准

# <主题>

## 目标
<用一段话说明当前问题和预期结果，不重复边界或方案>

## 决策基线

### 需求边界
<记录支持场景、正常与失败行为、明确不做及兼容要求；不讨论组件和文件>

### 技术决策
<记录职责、状态所有权、核心机制、接口、数据、存储、迁移、安全等 plan 不得自行改变的高阶结论；只为真实取舍保留必要理由>

## 设计视图

### 功能设计
<将需求边界综合为完整功能，说明入口、交互、状态、正常与失败行为及功能间关系；不逐条复述需求>

### 技术设计
<将技术决策综合为端到端实现方案，说明系统如何实现功能设计；足以指导 implement 细化实施，但不展开任务步骤>

#### 整体方案
<说明系统组成、组件职责、状态与数据所有权、接口边界、依赖关系及协作方式；存在跨模块拓扑、数据流、控制流或状态迁移时，可使用 Mermaid 图辅助，但图不代替关键职责和约束的文字说明>

#### 关键结构（按需）
<展开影响实现的数据模型、状态、接口或组件关系>

#### 实现流程
<从入口到结果写清主要调用、状态变化、异步处理、失败收敛和清理，形成全局实施指导而不是任务清单>

### 预估改动面
<按模块或目录说明预计变化、测试范围和已确认的 wiki 目标；作为 implement 的探索起点，不是硬边界>

## 验收
<覆盖正常行为、重要失败场景和兼容性；逐项使用以下格式>
- <场景或约束 → 可观察结果；验证证据>

通用规则

• 每项结论只有一个权威定义；决策基线定义不可改变的需求边界和技术选择，设计视图负责将其综合为功能与技术方案，不引入未确认决策或与基线冲突。
• 以最少文字完整表达所有影响实现或验收的已确认结论；合并重复信息，不省略理解方案所需的背景、需求边界、技术选择、关键结构与流程、预估改动面和验收证据；不展开 plan 级任务拆分。

自我审查

1. 覆盖：所有已确认需求和技术结论都有权威定义，并在功能设计、技术设计和验收中得到完整落实。
2. 分层：决策基线定义边界与选择，功能设计说明功能如何工作，技术设计说明系统如何实现，验收验证最终结果；各层没有矛盾或重复定义。
3. 交接：功能与技术设计足以让 implement 理解入口、职责、状态、流转、失败收敛和兼容边界，并据此细化文件和任务，无需重新决定核心实现方案。
4. 闭合：验收均有可观察结果和验证证据，文档中不存在占位符、未决项或可产生两种理解的表述。

发现问题就地修复，通过后再交给用户审阅。