ns-sdd-clarify-requirements

澄清需求

预规划工作流：在调用 ns-sdd-requirements-generator 之前识别并消除歧义。

查找 Harness

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

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

技术栈和架构问题属于技术栈检测范畴，不属于此技能。

适用场景

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

工作流

步骤 0 — 棕地项目检查（分析前）

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

1. 检查 {product_root}/docs/context/brownfield-map.md。
2. 检测 {product_root} 下的棕地项目信号：backend/、frontend/、src/、app/ 或同类应用程序代码（仅包含文档的仓库除外）。
3. 如果存在棕地项目信号，但缺少 brownfield-map.md：
   • 停止——暂时不要提出澄清问题。
   • 调用 ns-harness-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. 使用自然对话向用户说明此检查（与对话语言一致；下方提供英文模板）。不要使用阶段术语、Reply: 或电报式状态摘要。参见 ../ns-spec-driven/references/human-communication.md。

There's already a codebase map at docs/context/brownfield-map.md
(last updated {date from file, or "date unknown"}).

Want me to re-scan the repo and update it, or keep this one and move on to scope questions?

- refresh — re-scan and update the map
- keep — use the map as-is

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

如果存在，还要读取 {product_root}/docs/context/system-reverse-spec.agent.md（优先于正文内容）；否则，在检查完成后读取 system-reverse-spec.md。

步骤 1 之前允许读取的内容（棕地项目）：用户的范围文件、brownfield-map.md、system-reverse-spec.agent.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 个问题
• 优先询问影响功能正确生成的阻塞事项
• 尽可能将相关问题归组
• 使用通俗语言，编号清晰、内容完整——采用对话语气，而不是表单（Reply:、Premise:、技能名称）
• 绝不要说“在 Clarify/Specify 之前”——用通俗语言说出下一项交付物

呈现（根据对话调整语言）：

A few open points before I draft the requirements document:

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

Answer in your own words — no special format needed.

步骤 3 — 汇总回答

收到回复后：

1. 用简短摘要（3–5 个要点）确认理解
2. 用通俗语言提问：“要我接下来编写需求文档吗？” — 禁止：“go for Specify”、“proceed to Specify”或使用阶段名称的指令
3. 等待肯定答复或更正
4. 最多进行一轮澄清——如果仍不明确，将合理假设记为“假设前提”

步骤 4 — 移交给 ns-sdd-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]

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

关键规则

• **没有映射的棕地项目：**先运行 ns-harness-bootstrap-brownfield——绝不要跳过此步骤，改为通过 grep 搜索代码库
• 已有映射的棕地项目：步骤 0.4 的关卡必须执行——显示最近一次映射的日期；等待用户明确回复 refresh 或 keep；绝不要自行假设
• **与用户对话：**使用自然语言；说出交付物（“需求文档”），而不是阶段名称（“Specify”）；绝不要把对话压缩成电报式短语
• 最多一轮提问——之后采取保守假设并记录前提
• 此工作流不编写需求文档
• 不询问技术栈/架构——遵循技术栈配置文件、项目规则和棕地项目映射
• 如果用户对关键问题回答“不知道”：采用范围最小且最安全的假设，并记录下来

集成

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

棕地项目刷新关卡：在用户看到 brownfield-map.md 的日期后，必须由其确认 refresh 或 keep。

相关技能

• ns-harness-bootstrap-brownfield — 代码存在且缺少 brownfield-map.md 时的强制前置步骤
• ns-sdd-requirements-generator — 澄清后的下一步
• ns-harness-architecture-rules — 当 architecture-rules.md 仍是存根时使用的章程（与此技能分开）