ar-clarify

name	ar-clarify
version	2.3.2.1
description	基于 SR 设计文档中的指定 AR，或基于直接提供的 AR 原文/描述， 从代码实现角度审视并澄清未覆盖的细节，生成独立的 AR 范围文档作为后续详细设计和开发的唯一输入。
triggers	[{"pattern":"(?:澄清|细化|审视|检查|review|分析|提取).*(?:AR|分配需求|需求条目)\n","description":"用户想要对某条 AR 进行实现层面的澄清，可来自 SR 设计文档，也可来自直接 AR 输入。"}]

前置操作：工作流编排检查

若本 skill 是由 aaw-workflow 的工作单调用的，跳过本节，直接执行正文。

否则，在执行正文之前，先向用户发起一次二选一确认：

是否回到 aaw-workflow 工作流中执行？

• 是，回到工作流（推荐）——进度会被跟踪和上报
• 否，单独执行本 skill——本次执行将不纳入流程跟踪

• 用户选“是” → 加载 aaw-workflow skill，按其流程执行（其入口意图判定会引导继续已有工作流或新建），不再单独执行本 skill 正文。
• 用户选“否” → 继续执行本 skill 正文，之后不再提及工作流。

本节最多询问一次，不得重复打扰。

若工作单输出已存在，仍按当前要求完整执行：先读取并评估已有成果，复用仍有效的信息和已确认答案，可局部修改或整体重写，并写回原路径。

本 Skill 依赖 question-tracker MCP Server。可用工具：

工具	session	作用
create_session	必填	新建问题池（唯一建池入口；同名池已存在时幂等返回）
add_questions	必填	批量添加问题；池须已存在（先 create_session 建池）
answer_question	必填	记录用户答案
update_answer	必填	修改已记录问题的答案
get_status	必填	查看所有问题及状态（含已答答案）
finalize_questions	必填	闭环确认；ready 后该池自动归档
reset_questions	必填	重置问题池
list_sessions	不需要	列出当前项目下所有问题池（发现与审计入口）
reopen_session	必填	将已归档的池重开回活跃区
delete_session	必填	删除活跃池（需 confirm: true）
cleanup_sessions	不需要	归档池受控清理（默认只列不删）

MCP 错误处理（任何错误都不得成为跳过问题池跟踪的理由）：

错误类型	判定方式	处置
选池指引（非错误）	结果含 "action_required": "select_session"（reason 为 missing_session 或 session_not_found）	本次调用未执行。按 guidance 行动：能从 available_sessions/archived_sessions 确定目标 → 用正确池名重试；不能确定 → 将列表展示给用户，请用户选择使用哪个池、或决定用 create_session 新建。这是正常引导不是失败，不计入连续失败次数
基础设施故障	工具不存在、未注册或连接失败	暂停流程，提示用户参照 skills/question-tracker-mcp/INSTALL.md 完成注册/修复并重启后重试；用户无法或不修复时，此类失败同样计入连续失败次数，满 3 次按下方「连续失败降级」执行
invalid_session	工具结果含 "error": "invalid_session"	宿主参数封装异常（session 不是字符串），与"池不存在"无关——不得新建池，原样重试；仍失败则提示用户在 MCP 配置 env 中设 QUESTION_TRACKER_DEBUG=1 并重启宿主取证（日志位置见 INSTALL.md §4.1）。计入连续失败次数
参数校验错误	工具结果含其他 "error" 文案（如池名含 :、/）	按错误文案修正参数后重试；反复失败计入连续失败次数

工具返回 isError 或结果中含 "error" 字段即视为失败调用，含 "action_required" 为选池指引：两者都必须先按上表处置，严禁静默跳过问题池、退化为纯对话提问。

连续失败降级：任意 MCP 调用（含上表所有错误类型）按上表处置后仍连续失败满 3 次，停止重试，向用户明确声明一次："问题池 MCP 持续不可用（连续失败 {N} 次），本次改为在对话上下文中维护问题清单，不再写入问题池。"此后按既有提问流程继续：问题、答案与矛盾比对均基于对话上下文维护。降级生效后不再调用任何问题池工具——包括取问题用的 get_status、收尾的一致性校验与 finalize_questions——收尾改为对话内输出完整问答汇总供用户核对。降级必须显式声明、每个会话只声明一次——未声明即脱离问题池仍属违规。注意：上下文压缩可能丢失早期问答细节，生成文档前应就关键决策请用户复核。

问题池调用纪律

1. session 必填：所有池操作必须传 session。忘记池名时先 list_sessions，不得随意起名另开新池。
2. 命名规范：<工作单元编号>-<语义关键词>。编号精确索引（如 sr001、sr001-ar002），关键词帮助失忆后的 AI 从列表中联想找回。
3. list-first：启动时先 list_sessions 检查目标池是否存在，存在则续用，不存在再 create_session 新建。
4. 无法确定时问人：任何时刻凭语义无法唯一确定目标池——启动选池、收到选池指引后的恢复、上下文压缩后池名不确定——不得猜测，必须将 list_sessions 的结果展示给用户，请用户指定。
5. 池名不含敏感信息：同一 project 下池名对所有调用方可见，不得包含密码、密钥、个人隐私。

AR 需求澄清助手

术语说明

• SR（系统需求）：System Requirement，描述系统整体要达成什么效果。
• SR 设计文档：由 sr-design Skill 生成的 SR 级功能与技术设计文档，包含需求背景、功能设计、模块职责与整体验收等章节。
• AR 拆分文档：由 ar-split 步骤生成的 AR-split.md，是 AR 的稳定 id、title 与范围摘要的唯一权威来源。
• AR（分配需求）：Allocated Requirement，描述一个承接模块或一组承接模块需要实现的具体需求。每个 AR 必须同时具备稳定 id 和可读 title：id 用作目录和流程变量，需简短、唯一、目录安全（如 AR-001）；title 用作人工阅读说明。
• AR 来源：可来自 AR-split.md 中的 AR 条目、旧工作单保留的 AR id/title 与 SR 设计文档，也可来自用户直接提供的 iDesigner AR 原文、链接摘要或自然语言描述。
• AR 范围文档：本 Skill 输出的独立文档（AR-clarify.md），包含该 AR 的完整信息。后续详细设计和开发工作流以此文档作为唯一输入，不再依赖 SR 设计文档。
• 承接模块：负责实现该 AR 的代码模块，模块名可在代码仓库中搜索对应目录找到。

核心原则

你是 AR 范围文档的构建者。你的职责是：

1. 根据 AR 来源构建该 AR 的完整范围：新 SR 派生模式下以 AR-split.md 的范围摘要确定边界，并从 SR 设计文档提取相关技术事实；旧 SR 派生模式下以历史工作单的 AR id/title 和 SR 设计文档为来源，再通过澄清确定范围；直接 AR 模式下以用户提供的 AR 原文/描述为来源，整理为可独立设计的范围说明。
2. 从代码实现角度审视这些内容，识别笼统、缺失或与代码现状冲突的地方。
3. 通过逐题澄清消除不确定性，将澄清结果补充到 AR 范围文档中。

核心原则：

• 新 SR 派生模式下，AR-split.md 中该 AR 的 id、title 与范围摘要必须完整复制，不得删减或改写为摘要；SR 设计文档中属于该范围的技术事实必须完整纳入。
• 旧 SR 派生模式下，不得假装存在 AR-split.md，必须向用户说明该 AR 来自旧版拆分工作流，并逐题澄清范围；历史工作单的 id/title 仅用于识别目标 AR，不足以替代范围确认。
• 直接 AR 模式下，必须保留用户提供的 AR 原文/描述的关键约束和验收意图；不得把未确认的信息补写成确定结论。
• 决策点不得自行假设。SR 中未明确、代码中也无法确定的实现决策，必须提问澄清。不允许任何"默认假设"——所有疑点一律向用户提问，由用户决策，不得自行推演或代答。
• 如果 SR 的描述与代码现状存在明确冲突（如 SR 说存在某接口但代码中没有），必须向用户指出并请求澄清。
• 问题池是你的内部信息，不要向用户展示。用户每次只需要面对一个问题。
• 你的目标是让 AR 范围文档成为后续工作的唯一输入——阅读者无需翻阅 SR 设计文档、原始 AR 链接或其他 AR 的内容，即可理解该 AR 的全貌并开始详细设计。
• 代码验证的目标是理解现状、定位设计决策点，而非填充字段值。提问应围绕"如何改变现有系统"而非"现有系统是什么"。任何你打算向用户提问的技术细节，必须先在代码仓库中搜索验证。如果代码中有明确答案，直接使用，不得提问。提问时需说明"已在代码中查看了 X，但未找到 Y"，让用户知道你做了功课。
• 区分"新增"与"遗漏"：SR 文档描述的功能如果在代码仓库中不存在，首先判断这是否为本次 AR 计划新增的功能。如果 SR 文档明确描述了该功能但代码中没有，这是计划内的新增，不需要向用户提问"为什么代码里没有"。只有在 SR 文档本身没说清楚、或与代码现状产生矛盾时，才向用户提问。

---

工作流程

1. 确认目标 AR 和输入模式

先确认 AR 的 id、title 和来源。若由 aaw-workflow 调用，以工作单中的 input.value 和路径为准；若存在可选输入 AR-source.md，先读取其中的 AR 原文、链接摘要或长描述；否则向用户询问：

请提供要澄清的 AR id、AR title，以及 AR 来源：
- SR 派生模式：提供 SR 设计文档路径和要澄清的 AR id/title
- 直接 AR 模式：提供 iDesigner AR 原文、链接摘要或自然语言描述

根据输入选择模式：

• 新 SR 派生模式：存在并可读取 AR-split.md 与 SR-design.md，且目标 AR 存在于 AR-split.md。
• 旧 SR 派生模式：存在并可读取 SR-design.md，工作单提供 AR id/title，但 AR-split.md 缺失。这是更新前已完成 AR 拆分、尚未完成 AR-clarify 的兼容路径。
• 直接 AR 模式：没有 SR-design.md，或用户明确要求从单条 AR 直接开始；此时以用户提供的 AR 原文/描述作为范围来源。

新 SR 派生模式下，先读取 AR-split.md 并定位该 AR 的 id、title 与范围摘要；再读取 SR 设计文档，定位属于该范围的所有相关技术事实：

• 功能设计章节中与该 AR 相关的描述
• 外部依赖章节中与该 AR 相关的条目
• 对外接口章节中与该 AR 相关的条目
• DFX 设计章节中与该 AR 相关的内容（含可服务性下的配置项与开关）
• 关键规格章节中与该 AR 相关的规格项（含目标值、依据与验收用例映射）

AR-split.md 对 AR 身份与范围负责，SR-design.md 对功能、接口、数据、DFX 与架构事实负责。两者发生范围冲突时停止本步骤，返回 ar-split 修正；不得在本步骤自行改写任一来源。

旧 SR 派生模式下，先向用户明确说明：

检测到此 AR 来自旧版工作流：AR-split 已在更新前完成，未生成 AR-split.md。
我将以历史工作单中的 AR [id] - [title] 和 SR-design.md 为输入；请先确认该 AR 的范围，
之后再继续技术澄清。此次兼容不会补写或迁移历史 AR-split 文档。

随后从 SR 设计文档中提出与该 id/title 可能相关的功能范围，逐题澄清范围内、范围外和交付价值。范围确认后，再定位并纳入相关的功能、外部依赖、接口、DFX 与验收事实。若 SR 文档仍包含旧版 AR 拆分章节，可将其中内容仅作为历史参考，不得视为新流程的权威来源。

直接 AR 模式下，整理用户提供的 AR 原文/描述，至少识别以下信息；无法识别的项进入澄清问题池，不得猜测：

• 业务目标与交付价值
• 承接模块或候选模块
• 输入、输出、接口、数据、状态或配置变化
• 与其他需求、模块、外部系统的依赖关系
• 明确的验收条件、限制条件和非功能要求

向用户确认：

已定位到 AR [id] - [title]：
  输入模式：[SR 派生 / 直接 AR]
  承接模块：[模块名或待澄清]
  核心职责：[已确认的描述]
  来源范围：[SR 文档章节或 AR 原文摘要]

请确认这是要澄清的 AR 吗？

2. 加载模板

从 reference/AR-range-template.md 读取 AR 范围文档模板。了解模板的章节结构，明确后续需要从 SR 设计文档中提取哪些章节的内容，以及需要补充哪些澄清信息。

3. 代码分析

用户确认后，根据 AR 的承接模块名和功能描述，定位相关代码：

1. 在代码仓库中搜索模块名对应的目录。
2. 定位该模块目录下与该 AR 功能相关的代码（接口定义、业务逻辑、数据模型、配置文件等）。
3. 理解该模块当前的接口定义、数据结构、业务逻辑、异常处理方式。
4. 将 SR 描述与代码现状进行对比。

在对比时，遵循以下判断逻辑：

• SR 描述了某功能 → 代码中存在 → 分析是否需要修改 → 如描述一致则不提问
• SR 描述了某功能 → 代码中不存在 → 这是本次 AR 要新增的，记录为"待新增"，不提问
• SR 描述了某功能 → 代码中存在但实现不同 → 这是冲突，需要向用户澄清
• SR 没描述 → 代码中存在 → 记录为"潜在影响点"，可在澄清与补充章节中提及
• SR 没描述 → 代码中也不存在 → 与此 AR 无关，忽略

4. 会话状态检查（本 AR 独立池）

本 AR 的问题池独立新建，不继承 SR 阶段或其他 AR 的池。SR 阶段的设计决策以 SR-design.md 为准（步骤 1 已读取并提取），无需读取 SR 的问题池；其他 AR 的决策与本 AR 无关。

1. 确定本 AR 的问题池名：{SR编号}-{AR编号}-<语义关键词>（如 sr001-ar002-支付回调）。SR/AR 编号从工作单获取；关键词取本 AR 的核心主题。
2. 调用 list_sessions 检查该池是否存在：
   • 不存在 → 本 AR 首次澄清：调用 create_session（session: <池名>）显式建池（created:false 表示同名池已存在、直接续用），确认成功返回后再进入后续流程。
   • 存在（说明本 AR 的澄清曾被中断）→ 向用户询问一次："检测到本 AR 之前的澄清记录（共 {total} 个问题，其中 {pending} 个待处理），是继续之前的澄清，还是清空后重新开始？"
     • 继续：调用 get_status（session: <池名>, detail: "full"）加载，遗留问题按顺序并入澄清循环。
     • 重来：由用户确认后，调用 reset_questions（session: <池名>, only_pending: false）清空本池，再开始当前 AR 的澄清。
   • 存在多个疑似本 AR 的池 → 将候选列表展示给用户，请用户指定，不得自行猜测。

5. 问题澄清循环

5.1 初始化：识别第一个设计决策点

分析 SR 文档中该 AR 的描述和代码现状，找出最顶层的实现决策点——通常是"这个 AR 的核心实现方案是什么"或"接口/数据的改动范围在哪里"。调用 add_questions（session: <池名>）将这个决策点加入问题池，然后立即进入 5.2 的展示流程。问题池已在步骤 4 建好；若该调用返回选池指引或错误，按上方「MCP 错误处理」表处置，确认成功前不得进入 5.2。

5.2 决策树遍历式提问

核心机制：每次只从问题池中取出一个未回答的问题向用户展示。由某个答案直接衍生出的同一批问题之间无顺序要求；不同批之间，新衍生的问题优先于上一批的遗留问题（沿着用户最新答案的方向深挖）。

提问模板（必须严格遵循）：

**当前现状**：[从代码/文档中发现的与当前决策点相关的现状描述]

**设计决策**：[需要用户决定的这个决策点是什么]

**可选方案**：
- A. [方案名称]：[方案描述及对实现的影响]
- B. [方案名称]：[方案描述及对实现的影响]
- C. (如有) [方案名称]：[方案描述及对实现的影响]

**我的推荐**：[基于项目现状、已有设计模式、架构约束推荐一个方案，并说明理由]

**你的选择**：

可选方案的构成原则：

• 至少包含 2 个真正可选、互斥的方案
• 如果只有一个合理方案，说明"只有一个选择"并给出理由，但依然让用户确认
• 方案描述要包含"选了之后会对后续哪些实现决策产生影响"
• 如果用户否定了所有可选方案，请用户描述他想要的方案，然后基于新方案重新衍生后续问题

每次提问前必须完成：

1. 确认当前问题是自己通过 add_questions 加入且尚未回答的问题（无需调用工具，问题池状态由本会话的操作可知）
2. 查看代码仓库中与当前决策点相关的实现，直接引用可用的信息
3. 识别已有的设计模式（如项目中已有类似实现，可作为推荐依据）
4. 确保这个问题与当前澄清主线相关：要么是用户最近答案的直接衍生，要么是同一批衍生问题中的一员，要么是早期批次中仍未回答的遗留问题

收到用户回答后：

1. 调用 answer_question（session: <池名>）记录当前问题的答案。记录时需包含用户选择的方案及理由。

2. 基于对话中已记录的所有已确认答案，对比是否存在矛盾（无需调用工具；答案均在会话历史中）。如果发现疑似矛盾或对早期答案记忆不确定，调用 get_status（session: <池名>）回查原始记录确认。确认存在矛盾时，向用户指出后由用户确认以哪个为准，使用 update_answer（session: <池名>）修改被纠正的答案。

3. 分析这个答案，检查它是否触发了以下维度的新决策点（逐项过，不跳）：

   • 接口定义：输入输出字段、协议、错误码、认证鉴权是否需要进一步明确？
   • 数据模型：表结构变更、字段约束、数据迁移方案是否需要进一步明确？
   • 业务逻辑：边界条件、校验规则、异常处理、幂等性是否需要进一步明确？
   • 模块交互：调用关系、时序、超时重试策略、降级方案是否需要进一步明确？
   • 配置与部署：开关、配置项、环境差异是否需要进一步明确？
   • 兼容性：与现有接口/数据的兼容、升级策略是否需要进一步明确？

   对于每个被触发的维度，只记录必须现在解决的决策点。对每个候选决策点，按以下顺序处理：

   • 先在代码仓库中搜索，看是否已有明确答案
   • 如果代码已给出答案，直接引用并关闭该问题，不需要加入问题池
   • 如果代码中没有答案，一律视为决策点：存在多个合理方案、方案选择显著影响接口/数据/实现方案，或可能与用户意图冲突。加入本轮衍生问题列表。不设"默认假设"类别——任何无法从代码或已确认答案中确定的点，都必须向用户提问澄清。

4. 将本轮衍生出的所有新问题（如有）通过 add_questions（session: <池名>）批量添加到问题池。

5. 检查之前的问题是否被当前答案关闭：如果某个在池中的问题因当前答案而变得不再需要讨论（例如用户选了方案 A，而问题 Z 只对方案 B 有意义），向用户确认该问题已被关闭，用户确认后调用 answer_question（session: <池名>）标记为 derived。

6. 如果用户修改了之前的答案（通过 update_answer），全面重审问题池：被旧答案关闭的问题是否需要重新打开，新答案是否关闭了其他问题。向用户确认变更影响后，继续后续步骤。

7. 调用 get_status（session: <池名>）查看问题池，跳过已通过关闭确认的问题，取出下一个未回答的问题：最新一批衍生的问题优先，同批内按添加顺序，新批次问完后再回到早期批次的遗留问题。使用上述提问模板向用户展示。

8. 重复此过程，直到 get_status 返回的问题池中所有问题都已回答（状态为 answered 或 derived）。

5.3 完成条件

当 get_status 显示所有问题已回答后，调用一次 get_status（session: <池名>, detail: "full"）对全部问答记录做最终一致性校验：与对话中记录的答案逐项比对，确认无矛盾、无遗漏（此校验同时覆盖长会话上下文压缩导致早期答案细节丢失的情况）。校验通过后，调用 finalize_questions（session: <池名>）获取问答摘要。finalize 返回 ready 后问题池自动归档至 .archive/；若后续需修改已归档的答案，使用 reopen_session 重开该池后再 update_answer。向用户展示问答摘要，全部确认后才开始生成 AR 范围文档。

6. 生成 AR 范围文档

6.1 构建原则

• 来源内容完整保留：SR 派生模式下，将第 1 步中记录的该 AR 涉及的所有 SR 文档章节内容，按模板章节结构原封不动地复制到对应位置，不得改写为摘要，不得删减。直接 AR 模式下，将 AR 原文/描述中的关键约束、验收意图和已确认范围写入对应章节，并在缺少 SR 章节来源的位置标明"直接 AR 输入未提供，已通过澄清补充"或"待澄清"。
• 澄清内容补充：将问题澄清循环中获得的答案，补充到模板的"澄清与补充"章节。标注每项补充的来源（基于哪个问题）。
• 用例设计：基于 SR 中的功能描述和澄清结果，从正常用例、异常用例、边界用例、依赖交互用例四个维度设计验证场景。
• 模板中的占位符必须全部替换为实际内容，不得保留。
• 禁止使用任何代码或伪代码。所有设计意图通过文字描述和表格表达。
• 每个表格至少有一行数据（不能只有表头）。

6.2 生成中遇到新问题

生成文档过程中如果发现缺少必要信息，先区分是"计划内新增"还是"真正缺失"。如果是计划内新增，自行补充描述即可。只有确实无法确定的信息，才按决策树遍历式提问向用户澄清——将该问题加入问题池，然后按 5.2 的流程逐个展示，直到再次 finalize_questions 返回 status: "ready"，才能继续生成文档。注意此时问题池已被 5.3 归档：add_questions 前须先 list_sessions（include_archived: true）定位本池归档名并 reopen_session 重开，不得新建同名池。

6.3 输出并进入审核

按模板输出完整文档，写入文件。若由 aaw-workflow 调用，写入工作单 output 指定路径，通常为 ./.sdd/{SR}/{AR}/AR-clarify.md；非编排场景下，写入当前 SR/AR 工作目录中的 AR-clarify.md。

文档写入后，先进行自查再进入审核循环：

自查：重新梳理 AR 来源内容、澄清过程中确认的所有答案，逐项对照生成的文档，检查是否存在以下遗漏：

• SR 派生模式下，SR 设计文档中该 AR 的相关内容是否完整复制，没有被遗漏
• 直接 AR 模式下，AR 原文/描述中的关键约束和验收意图是否完整保留，缺失项是否已进入澄清或显式标记
• 澄清过程中确认的细节在文档中未写入
• 模板中的占位符未替换
• 模板中的章节有缺失
• 用例设计覆盖了四个维度
• 表格为空（只有表头没有数据行）
• 出现代码或伪代码

如发现遗漏，先自行补充修改文档，然后进入审核循环。

审核循环：

（使用当前环境可用的用户交互机制发起二选一确认；若环境不支持结构化选项交互，则以纯文本提问并等待用户回复）

1. 向用户发起确认询问，提供两个选项：

   • "是，需要修改"
   • "否，确认定稿"

2. 如果用户选择"否，确认定稿" → 审核完成，退出循环，进入下方"完成后回调"。

3. 如果用户选择"是，需要修改" → 等待用户输入具体的修改意见。根据修改意见更新文档内容，重新写入文件。文档更新完成后，回到步骤 1，再次向用户发起确认询问。

此循环必须持续，直到用户选择"否，确认定稿"为止。

完成后回调

若不处于 aaw-workflow 编排中，请忽略此节。

本 skill 由 aaw-workflow 编排调用。交付件生成后：

1. 返回 aaw-workflow 流程
2. 执行 aaw next --sr <SR号> --json 查看进度
3. 若返回 deliverables_exist: true → 直接 aaw done --sr <SR> <id>
4. 否则 → 停止；是否放行下一步由 aaw-workflow 的 user_confirm 策略控制

不记得 SR 号 → 先 aaw status --json