clarify-requirements

明确需求

规划前工作流：在调用 requirements-generator 之前识别并解决歧义。

查找 Harness

参阅 ../nextstage-harness/references/harness-discovery.md 和 ../nextstage-harness/references/artifact-layout.md。

**确定 {product_root}：**读取仓库入口处的 AGENTS.md。优先使用文档中记录的锚点。如果路径不存在、位于当前工作区之外，或指向另一个克隆，请使用包含 AGENTS.md 的目录。

技术栈和架构问题应归入技术栈检测，不属于此技能。

适用场景

• 用户提供的范围含糊或不完整
• 术语含义模糊（仪表板、集成、通知系统）
• 没有既有文档的新系统首个版本
• 编排器判断范围过于单薄（少于 3 段，或包含模糊术语）

工作流

步骤 0 — 棕地项目关卡（分析前）

在完成此步骤之前，不要搜索或探索应用源代码。

1. 检查 {product_root}/docs/context/brownfield-map.md。
2. 检测 {product_root} 下是否存在棕地项目信号：backend/、frontend/、src/、app/ 或同类应用代码（不包括仅含文档的仓库）。
3. 如果存在棕地项目信号，且缺少 brownfield-map.md：
   • 停止操作——暂时不要提出澄清问题。
   • 调用 bootstrap-brownfield 并生成 {product_root}/docs/context/brownfield-map.md。
   • 简要告知用户，在细化范围之前需要先了解棕地项目背景。
   • 地图文件存在后，从步骤 0.4（刷新关卡）恢复此技能。
4. 如果是绿地项目（没有应用代码）——跳过引导，继续步骤 1。
5. 如果 brownfield-map.md 已存在——在进行任何范围分析之前，先执行步骤 0.4。

步骤 0.4 — 棕地项目刷新关卡（必须由人工确认）

停止操作。在人工回复之前，不要继续步骤 1。

1. 读取 {product_root}/docs/context/brownfield-map.md。
2. 从文件头部的 **Date:** 行提取地图日期。如果缺失，请注明 date unknown。
3. 向人工呈现此关卡：

Brownfield map found: docs/context/brownfield-map.md
Last updated: {date from file, or "date unknown"}

Before clarifying this version's scope, do you want to refresh the brownfield map
(re-scan codebase with bootstrap-brownfield) or keep the existing map?

Reply with one of:
- refresh — update brownfield-map.md, then continue clarification
- keep — use the existing map as-is and continue clarification

4. **等待明确回复。**有效答复：refresh / keep（或自然语言中的明确等同表达）。
5. 绝不能因为地图看起来很新、规划很紧急，或用户已经粘贴了描述，就擅自认定为 keep。
6. 用户回复 refresh 时：调用 bootstrap-brownfield（原地更新），然后使用新地图继续步骤 1。
7. 用户回复 keep 时：在会话上下文中记录人工已接受日期为 {date} 的地图；继续步骤 1，并使用现有文件。
8. 回复含糊时：再询问一次——在明确得到 refresh 或 keep 之前，不要开始步骤 1。

关卡完成后，如果 {product_root}/docs/context/system-reverse-spec.md 存在，也要读取该文件。

步骤 1 之前允许读取的内容（棕地项目）：用户范围文件、brownfield-map.md、system-reverse-spec.md、{harness_root}/rules/architecture-rules.md、当前版本对应的 {product_root}/docs/versions/{version_san}/ 下的文件。

**步骤 1 之前禁止的操作：**为了“减少歧义”而在 backend/、frontend/ 或 src/ 中临时使用 grep 或进行代码搜索；存在地图文件时跳过步骤 0.4。

步骤 1 — 分析原始范围

阅读用户描述（以及步骤 0 适用时的棕地项目背景）。标记歧义：

类别	示例
参与者	“用户执行 X”——具体是哪种角色？
数据范围	列出字段、分页、筛选条件？
集成	REST、Webhook、认证方式？
多租户	是否需要隔离不同公司？
业务规则	具体要执行哪些验证？
状态生命周期	允许哪些状态转换？
范围限制	此版本包含或排除哪些内容？
性能	规模、并发量、SLA？
安全性	是否需要认证、角色权限？

利用棕地地图了解现有内容——只向用户询问此版本应更改或新增的内容。

步骤 2 — 提问

• 每轮最多 5 个问题
• 优先询问会妨碍正确生成功能的问题
• 尽可能将相关问题归组
• 使用通俗语言，编号，并确保每个问题都能独立理解

呈现：

Before generating requirements, I need to clarify a few points:

1. [actor question]
2. [data scope]
...

Reply in free form. I will proceed with requirements once I have these answers.

步骤 3 — 汇总回答

收到回复后：

1. 用简短摘要（3–5 个要点）确认理解
2. 询问：“要继续生成需求吗？”
3. 等待用户确认或纠正
4. 最多进行一轮澄清——如果仍不清楚，将合理假设记录为“假设前提”

步骤 4 — 移交给 requirements-generator

整理补充后的上下文：

## Original scope (user-provided):

[original text]

## Brownfield context (if applicable):

[Summary from brownfield-map.md — modules and constraints relevant to this version]
[Brownfield gate: human chose refresh | keep on {date shown in gate}]

## Clarifications obtained:

1. Question: [...]
   Answer: [...]

## Confirmed premises:

- [Premise 1]
- [Premise 2]

将此文档作为输入传递给 requirements-generator。此处不要编写 requirements.md。

关键规则

• **没有映射文件的 Brownfield 项目：**先运行 bootstrap-brownfield——绝不能通过搜索代码库来绕过此步骤
• **有映射文件的 Brownfield 项目：**必须执行步骤 0.4 的关卡——显示最近的映射日期；等待用户明确选择 refresh 或 keep；绝不能自行假设
• 最多一轮提问——之后保守地做出假设，并记录前提
• 此工作流中不生成需求文档
• 不询问技术栈或架构问题——交由技术栈配置文件／项目规则和 Brownfield 映射处理
• 如果用户对关键问题回答“不知道”：假设最小且最安全的范围，并记录这一点

集成

planning start → [brownfield + no map?] → bootstrap-brownfield → [brownfield refresh gate] → clarify-requirements → requirements-generator → Gate 1

Brownfield 刷新关卡：用户查看 brownfield-map.md 的日期后，确认选择 refresh 或 keep。

相关技能

• bootstrap-brownfield——代码已存在但缺少 brownfield-map.md 时的必备前置步骤
• requirements-generator——澄清后的下一步
• architecture-rules-generator——当 architecture-rules.md 仍为存根时使用的规范（与此技能分开）