ns-requirements-enricher

需求完善器

一个问题或一段粘贴的描述。输出 = 面向编码 Agent 的实现简报。只有在能解除实现阻碍时才提问。不创建分支、代码、状态或版本制品。

不是产品经理澄清。不是 SDD Specify / version Clarify。参见关系。

模式检测

模式	触发条件	交付内容
Issue	ISSUE_URL 或用户指向 GitLab issue	在聊天中预览评论正文。只有人类验证草稿后，才在内部调用 add_issue_comment
Chat	粘贴或描述范围——没有 issue URL	在屏幕上提供简报。绝不提出发布。绝不询问“要我发布吗？”

第 2–4 阶段共用。第 1 阶段（MCP 加载）仅用于 issue。

**MCP 回退（SSoT）：**GitLab MCP 缺失或不可用 → 按 chat 模式处理（提供相同简报；不发布）。不要停止。跳过第 1 阶段。

会话启动

参见 ../../ns-harness/references/session-boot.md。在 MCP 或代码库调查之前，必须完成会话启动（阻塞项）。

启动后使用 GitLab MCP：遵循 mcp-gitlab-usage（首次访问时执行 get_mcp_gitlab_skill 版本检查）。缺失 → MCP 回退。

目标

Issue 模式——问题留在聊天中。问题会形成评论。它们绝不会发送到 GitLab。收到回答后，展示已定稿的简报。只有在人类明确同意后，才发布该正文。

允许发布的评论：

1. 第一行是 ✅——需求已明确。不要使用 @mention。
2. 完整的实现简报（已纳入所有决策）。不要包含“问题”部分。不要列出推荐项。不要添加按编号回复的页脚。

Chat 模式——提出相同的问题，然后在聊天中直接展示已定稿的简报。不提供 GitLab 发布选项。不是 PRD。

不要实现、提交、更改 issue 状态、创建文件、写入 requirements.md，或调用 start_execution_planning。

适用场景

• 使用 ISSUE_URL，并在编码前准备简报（issue）
• 在聊天中粘贴简报/范围/AC，不涉及 GitLab（chat）
• 当实现 Agent 否则会猜测产品意图时，逐项追问
• ns-autonomous / 人类标记了信息不完整
• 在 ns-execution-gitlab-issue 之前执行的步骤，适用于验收条件不完整的情况

前提条件

1. 遵守宿主上下文中的 AGENTS.md——如果调查涉及测试/服务，则遵守 Docker/运行时要求。绝不要用工具读取它。
2. 若存在 agents.local.md → 只使用其中指定的 GitLab MCP。
3. MCP 可用时遵守 MCP 工具契约；否则使用 MCP 回退。

输入

变量	必需	说明
ISSUE_URL	仅限 Issue 模式	完整的 GitLab issue / 工作项链接
需求文本	仅限 Chat 模式	用户消息、粘贴的简报或附带的范围说明

不自动发布。DRY_RUN 已弃用——始终预览；只有在人类验证后才发布。

第 1 阶段——加载 issue 上下文（仅限 issue 模式）

**Chat 模式下跳过。**Chat 的来源 = 用户消息 + 粘贴的上下文。

解析 URL，获取 project_id（或用于发现项目的 project_name）+ issue_iid。

必须读取：

1. read_issue——标题、描述、标签、里程碑、负责人、相关链接。
2. list_issue_comments——完整讨论串；评论正文是需求来源。

评论中不要@mention 任何人。无论是创建者、负责人，还是从现有机器人评论中复制的登录名，都不可以。缺少 author.username 不构成停止条件。

综合整理（内部处理；尚未发布）：

• 目标——用一句话说明：完成后会有什么？
• 验收条件——从描述中列出；每项标记为清晰 / 部分明确 / 缺失
• 约束——标签/里程碑/截止日期仅供_你_了解；不要把缺失的标签变成问题
• 已回答事项——评论中能消除歧义的信息；不要重复提问
• 上游决策——参见下文的上游产品决策

用户声称使用 issue 模式，但未提供 ISSUE_URL：用一句话停止——缺少 URL。不要编造 issue 内容。MCP 不可用不属于此停止情形——应使用MCP 回退。

**Chat 模式：**同样从对话文本整理目标 / AC / 约束 / 已回答事项。

上游产品决策

如果工作区中有与此问题所属范围相关的 PM 文档，请先阅读，再提出任何问题：

• docs/versions/*/pm/decision-register.md：决策（Q-NN）、冲突（C-NN）、就绪状态
• docs/versions/*/pm/prd.md：每项需求的业务规则和验收标准、未解问题

按里程碑、标题或此问题要实现的需求进行匹配。如果无法确定，就使用最接近的匹配项，并在一行内部备注中说明是哪一项。不要就此提问。

上游状态	Enricher 操作
决策为 answered	已有答案。不要重复提问。将其写入简报，作为一项需求
此问题涉及的决策为 open / assumed	必须纳入问题批次，并采用上游建议的答案
问题文本与上游决策相矛盾	Contradiction 检测器。询问以哪种结果为准
没有 PM 文档	继续。自行执行业务决策扫描（第 3 阶段）

聊天中粘贴的 PRD 或决策列表与文件具有同等效力。

第 2 阶段 — 先检查代码库

确定所请求的行为在应用代码中已经存在、是对现有屏幕／流程／模块的扩展，还是全新的。

范围仅限问题／范围涉及的内容。代码仅作为内部证据。路径、类、文件、SQL、控制器保留在备注中。简报应说明需求：屏幕、列、用户看到的内容，以及必须做出的更改。

相关时阅读：

• docs/context/brownfield-map.md
• docs/context/system-reverse-spec.agent.md（优先），否则阅读 system-reverse-spec.md
• .nextstage-harness/rules/architecture-rules.md
• docs/context/gitlab-sync-config.md（仅作背景信息）

调查： 搜索符号／路由／模块；阅读控制器／服务／视图／API／集成；检查测试；记录当前行为、扩展点、权限、事件／队列、环境变量。

输出（用于编写简报）：

调查结果	简报用途
代码中已有该行为	说明当前屏幕的表现。不写路径。只有在请求会改变该行为且产品意图仍不明确时，才提出问题
扩展现有屏幕／流程	指明用户打开的屏幕。简报说明哪些内容保持不变、哪些内容会改变
未找到	简报说明该屏幕上的行为是新增的。仍然不要提及版本

不要运行版本 Clarify。不要编写 requirements.md、clarify-contract.md、unknowns-register.md、source/、任务文件、PO、里程碑即版本、Gate 0 版本范围。

第 3 阶段 — 精简提问（grill 技巧）

从 ns-spec-driven Clarify 借鉴技巧（references/clarify-requirements.md、clarify-strict.md）：编号问题批次；使用可观察的产品语言；区分阻塞项、假设项和省略项；检测未解决的价值判断和矛盾。

不要运行版本 Clarify 工作流（不执行 brownfield Step 0.4 中止、不设 Gate 0、不生成版本文档、不使用 skip clarify）。

交叉检查问题／聊天文本 + 评论 + 上游决策 + 代码。对于每个缺口：实施 Agent 是否会猜测产品意图？ 如果无需猜测 → 不提问。

业务决策扫描（必需）。 仅扫描文本中的歧义，会漏掉无人写明的内容。对于此问题新增或更改的每条业务规则，遍历业务维度和 references/question-checklist.md 中的十项规则探查（空值、并列、部分、重复、谁可以操作、现有数据的默认值、撤销、用户忽略、使用哪个日期、还有哪里）。扫描范围仅限问题涉及的内容。一个只有一行的 UI 修复不必检查完整清单。

没有阻塞缺口： 表明已就绪。不要编造凑数内容。

给开发者视角的检查（在说“已就绪”之前）。 以编码 Agent 的身份重读简报草稿，假设无法访问此聊天。它仍会提出的每个业务问题都要加入问题批次。聊天中已作出但简报未包含的每项决策都要写入简报。技术问题（算法、架构、库）不要纳入。

受众

向此聊天中的用户提问——使用产品语言，而非开发、技术负责人或运维语言。不要 @ 对方。

• 语言：常见的产品/UX 用语（屏幕、按钮、筛选器、显示内容、显示时机）
• Schema、SQL、类、分支、标签、文件路径 → 仅供内部记录。绝不能出现在问题列表或需求简述中。

该提升为问题、作为假设还是舍弃

情况	操作
缺少该产品事实时，Agent 无法确认是否完成	编号提问 并附上推荐方案
业务决策：套餐或用量、谁可以执行、现有客户的默认设置、金额或舍入、导出内容、不可逆操作、改变客户已验证的现有行为、个人数据或第三方	编号提问 并附上推荐方案，绝不能悄悄设为假设，即使默认值看似显而易见
安全的默认选项（布局、措辞、屏幕上已有的 UI 模式），且 Agent 无需提问即可交付	列为假设——不要提问
已在描述/评论/代码中	舍弃
可有可无/工程偏好	舍弃或列为假设

问题质量

• 面向需求方，明确指出具体屏幕/流程，一句话或封闭选项即可作答
• 只问阻塞项。按用户旅程编号，格式为 1. 2. …
• 最多 15 个。合并细碎问题
• 一轮问完所有阻塞项——不要逐步追问（issue 模式下缺少上下文时除外）

问题格式（N ≥ 1 时必须遵守）

先在聊天中提问。不是 PRD。每个问题都要附上编码 Agent 在对方接受时会采用的默认方案。

Q{n} — {short title}
{What the screen does vs what the request says. One or two sentences.}

➡️ Recommended: {concrete default. Name what changes and what stays.}

严格要求。 分为三个区块：标题行、正文行，然后是一个空行，接着在下一行写 ➡️。箭头放在句号后的同一行是无效格式。在箭头单独占一行之前，不要发送问题。

无效：Q1 — 标题 屏幕隐藏了部分行。 ➡️ 推荐方案：重新显示这些行。

按回复其余内容所用的语言翻译此标签（葡萄牙语用户：➡️ Recomendado:）。

3. 结尾须使用与用户相同的语言：按编号回复（1: …、2: …）。是/否问题可以回复“全部是”或“全部采用推荐方案”。然后在此聊天中确认需求。不要提及 PRD、版本或 PO。

仅限聊天。 此批内容用于撰写需求简述。禁止将问题、Recommended: 行以及按编号回复的结尾内容写入 add_issue_comment 的正文中。

推荐方案 = 根据代码得出的安全产品默认选项。一旦对方接受，就将其作为决策写入“变更内容”“验收标准”或“假设”中。问题仍在聊天中待答时，不要只把默认方案藏在“假设”中。

检测器（仅适用于 issue 粒度）

编号	命中条件	处理方式
未明确的值	可见行为中出现 TBD、范围或含糊的形容词	在问题中明确，或在需求简述中列为假设并说明影响
矛盾	Issue 与评论、上游决策或当前代码不一致	询问应以哪种产品结果为准。不要悄悄自行决定
含糊的术语	名词存在两种合理解释（“公司”“账户”“用户”“标题”）	询问具体指哪一种，并推荐最可能的含义
范围外溢	此处行为取决于已声明为范围外的内容，或新规则可能改变现有流程	询问该规则仅适用于此处，还是也适用于现有流程，并推荐“仅适用于此处”

不属于检测项： 缺少标签、分支名称、GATE 1、将里程碑当作版本、PO、完整版本措辞。

翻译技术问题

内部备注（绝不可发布）	询问需求方，然后将答案写成需求
表/列 / 类	“按 Club 筛选是否意味着只显示当前关联到该 Club 的人员？”
基础分支 / develop-*	不要询问
缺少 Team: *	不要询问
端点 / SQL 联接	“同时选择 Federation 和 Role 时，人员必须同时匹配两者，还是匹配其中之一即可？”

示例：

Q1 — When the filter applies
Today the date filter runs only after Search.

➡️ Recommended: same — checkbox applies only after Search.

绝不要询问： 缺少 Team 标签；使用哪个 develop_* 分支；使用哪个 SQL 关系。

问题清单范围之外

标签；基础分支；GATE 1；schema/class/env；“应如何实现”；将版本/PO/里程碑视为版本；为显得周全而添加的填充内容。

扫描类别：references/question-checklist.md。

阶段 4 — 实施说明

受众 = 编码 Agent。范围 = 此问题或粘贴的描述。消除实施方面的疑问。

填写 references/comment-template.md。必需部分：

部分	内容
当前行为	用户目前在指定屏幕上看到的内容。不提文件、类或路径
变更内容	需求差异。哪些内容保持不变
验收标准	Agent 可在屏幕上验证的步骤/结果，不是 OKR/RICE
假设	已接受的决策和安全默认值。若假设错误，会有什么影响

不得包含 文件 / 区域。不得使用 问题 标题。未解答的问题继续留在聊天问题批次中，直至纳入说明。不是版本 PRD。不是 PM OKR/RICE。不是 SDD Specify。

阶段 5 — 确认需求，然后通过 GitLab 门禁

N ≥ 1： 发送问题批次（采用阶段 3 的格式），然后停止。不要发布。不要提前粘贴 GitLab 正文。

收到回复后：将每个答案纳入说明。

回复	说明
接受推荐方案 /“全都同意”/“全部推荐”	将该默认方案移入变更内容或假设。删除问题
其他答案	将该决策写入变更内容/验收标准。删除问题
跳过某个编号	在聊天中再次询问。不要自行编造。在每项问题都有定论前，不要预览或发布

然后粘贴已确认的说明（模板）。正文中不得有问题。

模式	已确认的说明显示在屏幕上之后
Issue	等待。只有在人类明确确认该草稿（是 / 发布 / 等效表述）后，才使用 add_issue_comment 并设置 internal: true 发布。不得静默发布。若有修改 → 修订预览 → 再次等待
Chat	停止。已确认的说明就是交付内容。禁止： 提出发布；询问“要我发布吗？”；发布 GitLab 评论

N = 0： 不发送问题批次。粘贴准备好的说明，然后遵循相同的门禁流程。

已发布 / 预览的正文以 ✅ 和一行就绪提示开头，提示使用用户的语言（葡萄牙语：✅ Brief de implementação. **Pronto.**）。不要使用 @。如果正文是葡萄牙语，该提示也不得保留为英语。

仍有任何问题未解决时，不要发布。GitLab 中不存在 ❌ 版本。

实际发布后：在聊天中提供链接，或提供 project_id + issue_iid。

范围超出此问题的决策（仅限聊天，在已确认的说明之后另起一行）：列出刚刚作出的、同样适用于其他屏幕或问题的决策，以便需求方将其记录在团队其他成员会查看的地方。绝不要放入 GitLab 正文。

不要使用 set_issue_status、update_issue、create_issue、start_execution_planning。

语言

所有面向用户的输出都使用同一种语言：问题、➡️ Recommended 标签、结尾语、简短标题、首行、页脚。与用户使用的语言一致。用户用葡萄牙语，就用葡萄牙语回复——标题也一样（Comportamento atual、O que muda、Aceite、Premissas）。不要让英文标题与葡萄牙语正文混用。

references/comment-template.md 中的模板是英文框架。展示或发布之前，先翻译每个标题和页脚。除非用户用英语写，否则不要原样照搬英文标题。

• 聊天和简报： 不要包含文件路径、类名、SQL、环境变量、控制器。只写需求（屏幕、列、行为）

反模式

• 同一条回复中混用语言（英文标题、葡萄牙语正文，或反过来）
• 在聊天或 GitLab 评论中包含文件路径、类名、控制器或 Files / areas 部分
• 在 GitLab 评论中加入问题列表、Recommended: 行或“按数字回复”
• 未经人工确认已定稿的简报就自动发布
• 聊天模式：主动提出发布到 GitLab
• 逐个提问，而不是批量整理成简报
• 公开评论（非内部评论）
• requirements.md / start_execution_planning / 版本 Clarify 产物
• 实现或分支
• 将 ➡️ 放在问题正文同一行（句子。 ➡️），或其前面没有空行
• 将已定稿的简报称为 PRD
• 无意义的问题；笼统地问“应该如何运作？”
• 在假设中隐藏业务决策（计划、权限、现有客户的默认值、金钱、导出、撤销、个人数据），而不是提出问题并给出 Recommended 答案
• 重复询问上游已回答的决策，或忽略此问题涉及的上游未决事项
• 重复询问评论中已有的事实
• 在简报或 GitLab 评论中使用 @mention（问题提出者、负责人，或从其他评论复制的登录名）
• 开发问题（表、分支、标签、GATE、测试路径、JSON）
• 版本 / PO / 作为版本的里程碑 / “完整版本”相关表述
• 将此技能用于 PM OKR/RICE 或 SDD 版本 Specify / Clarify-Strict

与其他技能的关系

层级	技能	适用时机	颗粒度	不适用于
PM	ns-project-manager	接收需求 → RICE、PRD、预算、决策登记表	OKR、规模、利益相关者、全版本产品决策	不适用于此场景。其已确定的决策是此处的输入；若此问题涉及尚未确定的决策，则在此处询问
SDD Clarify-Strict	/ns-spec-driven	Specify 之前，Gate 0	磁盘上的版本	借鉴方法；不借鉴产物
Enricher（本技能）	/ns-requirements-enricher	为单个问题或粘贴的范围开始编码之前	单个问题的简报 + 数量有限的问题	预览后发布内部评论 或 仅限聊天的简报
Specify	/ns-spec-driven Specify	Clarify 之后	版本 requirements.md	不是单个问题的简报
Execute	ns-execution-gitlab-issue	简报内容明确之后	实现问题	不用于需求补充
Review	ns-reviewer	代码完成之后	Diff 审查	不用于需求补充
MCP	mcp-gitlab-usage	MCP 调用	工具契约	版本检查；不是目录的 depends

快速检查清单

• 模式：issue 还是聊天
• Issue：read_issue + list_issue_comments。简报中不含 @mention
• 聊天：根据用户消息综合整理；不加载 MCP issue
• 存在上游 PM 决策时，先阅读（已回答 = 不要询问；未解决 = 连同其建议一起询问）
• 先检查代码库：已存在 / 扩展 / 新建
• 扫描业务决策 + 对 issue 新增或变更的每条规则进行规则探测
• 说可以开始前，先从开发者视角检查
• 只有在实现 Agent 必须猜测时才提问；否则标记为就绪
• 每个未解决的问题：标题行、正文行、空行，然后在下一行写 ➡️。sentence. ➡️ 放在同一行无效。结尾说明：按编号回复，然后在聊天中补全需求。不是 PRD
• 收到回答后：生成已定稿的简报（将决策写入「变更内容 / 验收标准 / 假设」）。不写文件 / 涉及区域
• 整份回复使用用户的语言，包括标题。不要混用英语 / 葡萄牙语
• GitLab 正文中不能包含问题和代码路径。Issue：只有人工确认后才发布已定稿的草案。聊天：绝不提议发布
• 不要采用版本表述，不要更改状态，不要写代码，不要逐个问答

参考资料

文件	适用阶段
references/comment-template.md	阶段 4–5 — 简报 / GitLab 正文
references/question-checklist.md	阶段 3 — 差距扫描
../../ns-harness/references/session-boot.md	会话启动（阻塞项）