Requirement Clarification（需求澄清）

通过结构化的提问框架，把一个模糊、宽泛或存在分歧的需求，收敛成目标明确、边界清晰、可被评审和验收的需求说明，以及需求条目登记册（每条带唯一 ID、优先级、验证准则，符合需求管理规范的最小闭环）。本 skill 只负责澄清与定义，不进入技术实现。

本 skill 是 z-系列的中枢：上游用 z-pyramid 拆解大问题、z-chain 供给生态/干系人事实，产出供 z-assess 评估、z-init 基线化；整链编排见 z-flow-kickoff。

help 用法卡

调用消息或斜杠参数恰为 help / 帮助 / 怎么用（整条仅此一词）时，逐字输出本卡后停，不进入任何流程；请求含其他内容时按正常流程走。

【z-clarify 用法卡】需求澄清——把模糊需求问成"澄清报告 + 需求条目登记册"两件产物。

预期：约 10 分钟，答"不知道"也有效。跨系列问法（整链/组合/元命令）见 z-flow-kickoff help。

何时使用（When to Use）

• 用户给出一句话需求，但目标、范围或成败标准不明确
• 需求涉及多个干系人/团队，存在目标冲突或口径不一致
• 需要把业务诉求转成可评审、可验收的需求定义
• 尚未确定方向或策略，需要先锁定"做什么、不做什么"

当用户明确要求"确认需求""澄清需求""需求评审""方案评审""需求对齐""需求梳理""梳理边界""明确目标/范围"等时，优先调用本 skill；用户虽未点名、但意图是先想清楚"做什么、不做什么"时，同样调用。

核心原则

1. 先澄清，后方案：在目标、边界、成功指标明确前，禁止讨论技术选型或实现细节。
2. 区分三类陈述：把信息分成"事实（现状/约束）"、"判断（观点/偏好）"、"方案（怎么做）"，三者分开记录，避免混淆。
3. 渐进披露：先用开放性问题打开局面，再逐步收窄到具体细节，不要一上来就抛十几个问题。
4. 闭环确认：每轮提问后，把理解复述给用户确认，确保对齐再进入下一轮。

提问框架（10 个澄清维度）

按顺序依次澄清，每维度的答案都记录到最终输出中。维度并非都要提问，跳过前先说明为什么该维度不适用。

需求本身是大问题、需要先拆成子问题时，按 z-pyramid 的 issue tree 方法拆解（如已安装该 skill）；未安装时按 MECE 原则手动拆：相互独立、完全穷尽，拆完检查"有重叠吗、漏了什么"。

1. 业务背景（Why）

• 这个需求解决什么问题？现在是什么状况？
• 不做的代价是什么？
• 有没有必须对齐的行业规范或公司标准？

2. 目标（What goal）

• 一句话描述最终要达到的结果是什么？
• 有哪些可量化的目标（数值、时间、成本）？
• 目标优先级怎么排？哪一个是不可妥协的？

3. 方向与策略（How direction）

• 有几条候选路线？倾向哪条，为什么？
• 是一次性交付，还是分期演进？
• 是否有必须先验证的关键假设？

4. 角色与干系人（Who）

• 谁是最终用户？谁付费/决策？谁使用/维护？
• 各方期望是否一致？存在哪些冲突？
• 是否有必须照顾的弱势/特殊用户？

已由 z-chain 项目生态图覆盖时（治理/核心/链上/支撑四层），直接读图补空缺与待核项，不重复追问；未建图时按上述三问收集。

5. 当前流程与现状（Current state）

• 现在这个问题是怎么处理的？用什么工具/流程？
• 现有流程的痛点是什么？
• 有没有历史包袱或遗留系统要兼容？

6. 业务链与上下游（Business chain）

• 这个需求的上游输入是什么？下游输出是什么？
• 会触发哪些关联流程/系统/部门？
• 数据从哪里来、到哪里去？
• 生态链定位：这个事项处于行业/价值生态的哪一环？上游谁供给、下游谁消费？
• 生态关系：平行位上有谁（伙伴/竞争者/替代者）？这件事和它们是互补还是冲突？
• 卡位点：它依赖谁、被谁依赖？生态中哪个环节断裂影响最大？
• 完整图谱：需要把整条链/整个生态画成"谁扮演什么角色"的分层图谱（链长/链主、发起人/owner、三态标注、空缺留白）时用 z-chain——优先在澄清收口后另起一步建图，避免打断问答节奏；图建好后角色表回填本维度与维度 4 的空位。用户点名"现在就画"则当场切换。z-chain 未安装时按上面三问内置退化。

7. 规则与约束（Rules & constraints）

• 有哪些硬性规则（法规、安全、合规、SLA）不能违反？
• 有没有技术/预算/时间的硬约束？
• 哪些是可协商的，哪些是不可协商的？

8. 数据依赖（Data）

• 需要哪些数据？数据从哪来、质量如何、多久更新？
• 是否存在隐私/敏感数据需要特殊处理？

9. 成功指标（Success metrics）

• 怎么判断"做成了"？可量化指标是什么？
• 验收标准是什么？有哪些可测试的通过条件？

10. 风险与边界（Risk & boundary）

• 最坏情况下可能出什么问题？
• 明确不做什么（非目标 out-of-scope）有哪些？
• 范围的边界在哪里，什么情况下要重新评审？

输出格式

澄清完成后，输出一份结构化需求说明，包含：

需求澄清报告

 一、业务背景（Why）
 二、目标（Goal）          ← 一句话目标 + 可量化指标
 三、方向与策略（Direction）
 四、角色与干系人（Stakeholders）
 五、当前现状（Current state）
 六、业务链（Business chain）
 七、规则与约束（Rules）
 八、数据依赖（Data）
 九、成功指标与验收标准（Success & acceptance）
 十、范围边界（Scope & out-of-scope）
 附录A：待确认问题清单（本轮未决项）
 附录B：术语表（双方口径必须一致的词：术语｜定义｜来源）

每节用"结论 + 依据 + 未决项"三段式呈现：结论是澄清后的定义，依据是来自用户的原始陈述，未决项是需要后续跟进的问题。

各节结论按金字塔原理检验（z-pyramid 如已安装则加载之）：结论先行、每组同类、逻辑顺序成立、结论是有观点的判断而非事实罗列。

报告末尾附"质量自评"，按 5 项 rubric 打分（每项 2 分，满分 10 分），低于满分的项各给一句改进建议：

质量自评（x/10）

1. 结论先行：每节第一句给出结论，而非过程叙述        x/2
2. 同类分组：每节内容同类归组，无混排                x/2
3. 逻辑顺序：排序为演绎/时间/结构/程度之一           x/2
4. MECE：十维度覆盖无重叠、无遗漏                    x/2
5. So What：结论是有观点的判断，不是事实罗列          x/2

第二产物：需求条目登记册（需求管理规范的落地件）

报告输出后，从各节结论中提炼需求条目，形成登记册——这是叙事报告与可管理需求之间的桥：

| ID | 类型 | 需求陈述 | 来源 | 优先级 | 验证准则 | 状态 |
|----|------|----------|------|--------|----------|------|
| R-001 | 目标 | …… | 维度2·用户原话摘要 | Must | …… | 已确认 |
| R-002 | 功能 | …… | 维度1·痛点推导 | Should | …… | 待定 |
| R-003 | 约束 | …… | 维度7·用户原话 | Must | …… | 已确认 |

• 类型：目标 / 功能 / 约束 / 数据 / 指标（一条只装一件事，复合陈述拆条）。
• ID：R-001 起连续编号；进入 z-init 基线后不变更、不复用。
• 来源：必填——"维度 N·用户原话摘要"。无来源不入册（宁缺勿编，同 z-chain 铁律）。
• 优先级：MoSCoW（Must/Should/Could/Won't-this-time）；用户没表态的标"待定"并追问一次。
• 验证准则：可测试的通过条件；写不出的那条本身就是一个未决项，进附录A。推荐句式 EARS——"当[触发条件/事件]时，系统应[可观察行为]"（约束类用"系统应始终…"），或 GIVEN/WHEN/THEN；禁"友好、快速、灵活"式不可判词；目标/指标类条目不套 EARS，用可度量陈述（如"90 天内 ≥50 次成团"）。
• 状态：已确认（用户认可）/ 待定。

登记册随报告一并给出初稿，请用户只确认优先级与验证准则两列（其余列来自已确认的对话）；确认后与报告一起落盘。下游消费：z-assess 以此为评估证据，z-init 以此种子化 SRS 需求表与跟踪矩阵。

落盘（z-系列工作区约定）

• 项目语境下（当前目录是一个项目），最终报告与登记册默认写入：

docs/00-立项/需求澄清报告.md
docs/00-立项/需求条目登记册.md

• 落盘前用一句话告知写入路径；用户说不落就不落，只出对话产物。
• 已有同名文件：先给差异摘要，用户确认后再覆盖；未决项较多时也可另存增量版本并在文件头注明版本号。
• 基线后（部署期）：工程文档基线已存在（docs/01-需求/ 起）或用户明示已上线时，变更/新需求的澄清报告落 docs/05-管理/变更/需求澄清-<主题>.md，00-立项/ 已冻结不回写；新增条目 R-xxx 接续原登记册编号、随报告一并给出，由变更流程（z-init 变更控制）同步 SRS 与跟踪矩阵——本 skill 不直接改 SRS。
• 非项目语境（纯讨论、无工作区）不落盘。
• 报告落盘 ≠ 需求基线：基线化（git tag、变更控制）由 z-init 在项目确认后完成。

开场协议（完整级，z-系列工作模式）

进入本 skill 后、第 1 轮提问前先做开场确认——复述与第 1 轮合并在同一条消息（作答即视为确认开始，不单独占一轮）：

1. 复述理解：一两句重述"用户要做的事 + 期望产出"，必须含用户原话中的至少一个具体事实；存疑处列出请用户先纠正。
2. 交互计划：轮次安排（几轮、每轮问什么维度、什么形式——面板/卡片/文本）；报总预算与用户任务（如"约 4 轮 10 分钟、你主要做选择题"，答不上来说"不知道"也算有效回答，如实进未决项）。
3. 预期产物：需求澄清报告 + 需求条目登记册（项目语境含落盘路径）。
4. 当次边界：不做什么（如"本次不做技术方案"）。

被 z-flow-kickoff 编排进入时沿用其契约与横幅，本节自动满足；单独触发时按本节执行。

交互式向导（对话流程）

典型 3–4 轮收敛，按信息量增减，不要一轮问完，也不要超过 5 轮：

第 1 轮  业务背景 + 目标（维度 1–2）        ← 开局最关键，先对齐"为什么做、做成什么样"
第 2 轮  现状 + 业务链 + 数据（维度 5、6、8）
第 3 轮  约束 + 指标 + 边界（维度 7、9、10）
第 4 轮  复述全案 → 用户确认 → 输出需求澄清报告 + 需求条目登记册初稿

维度 3（方向与策略）、4（角色与干系人）视需求复杂度穿插在前两轮中。一句话小需求可压缩为 1–2 轮，最后一轮合并复述与登记册确认。第 4 轮确认负荷偏重时拆两步：先确认报告全案，再核对登记册的优先级与验证准则两列（可下一轮补确认），不要在同一条消息里要两样答复。

提问方式：

• 双栏面板模式（Gen UI 宿主，默认开启）：宿主支持会话内可视化（声明 Gen UI 且提供可视化目录，如 ZCode Desktop）时，第一轮回复就默认生成双栏面板——不先征求意见、不需要用户点名，直接给出第 1 轮面板加一句简短用法说明。面板文件写在可视化目录：左半幅为本轮 3–4 题与选项按钮（点选在面板内高亮，并同步右半幅对应维度的结论，选项说明带一句"选它意味着什么"），右半幅为需求澄清报告的实时状态（已选/本轮/待澄清 + 各维度计划轮次徽章 + 一行当前累积结论）；"提交本轮"按钮用 await window.zcode.sendFollowUpMessage({ prompt: "第 X 轮选择：Q1=…, Q2=…", title: "需求澄清 第 X 轮" }) 把选择发回模型，模型收到后更新面板、给结论快照并进入下一轮。每轮更新同一文件并在当轮回复中引用（引用格式见下方"面板生成规则"；本 skill 已自含面板配方，无需加载 visualize skill）。
• 卡片模式（退化路径）：仅当宿主不支持 Gen UI、或用户明确偏好轻量时才用——从第一轮开始就把每轮 3–4 个问题做成一次 AskUserQuestion 调用（每题 2–4 个选项，"其他"由宿主自动提供）；开放性问题也包装成"常见情形选项 + 其他"，只有真正无法枚举的深挖追问才用纯文本。
• 影响写进说明文字，preview 作增强：preview 字段在部分客户端不渲染（实测 ZCode 当前版本的问题卡片只显示选项列表，右侧预览面板不出现），不要依赖它承载必要信息。两种模式下，每个选项的说明都固定带一句"选它意味着什么"的极简影响（如"质检成本约翻倍"）；preview 字段照常带上——支持渲染的宿主会展示详细结论（多行、仅单选题），不支持时由说明文字与每轮快照兜底。

双栏面板骨架（Gen UI 模式复制后按当轮问题填充）：

<div id="clarify-panel">
  <style>
    #clarify-panel{color-scheme:light dark;display:grid;grid-template-columns:1fr 1fr;gap:12px;font-family:system-ui,sans-serif}
    @media(max-width:740px){#clarify-panel{grid-template-columns:1fr}}
    .cp-pane{border:1px solid var(--border);border-radius:10px;padding:12px;background:var(--card);color:var(--foreground)}
  </style>
  <div class="cp-pane"><!-- 左：本轮题干含"第 X/4 轮"，选项用 button，点选高亮并写入右栏对应维度 --></div>
  <div class="cp-pane" aria-live="polite"><!-- 右：十维度实时状态 + 一句结论，选项点击即同步 --></div>
  <button type="button"><!-- 提交本轮：await window.zcode.sendFollowUpMessage({ prompt: "第 X 轮选择：Q1=A, Q2=B", title: "需求澄清 第 X 轮" }) --></button>
</div>

面板生成规则（Gen UI 模式已自含，标准面板无需加载 visualize skill）：

• 面板文件写入宿主 Desktop 上下文声明的会话可视化目录，文件名用小写连字符（如 clarify-panel.html）；只写 HTML 片段——不要 doctype/html/head/body，根元素用唯一 id，CSS/JS 内联在片段里。
• 每轮更新同一文件；更新后在当轮回复的独立一行输出引用（不要包代码块、不要 markdown 链接）：

::visualize{"path":"<会话可视化目录>/clarify-panel.html"}

• 硬约束：面板 <1MB；无 fetch/网络请求；颜色只用 var(--card)、var(--foreground)、var(--border)、var(--muted)、var(--primary) 等主题变量，不写死色值；右栏动态结论区加 aria-live="polite"。
• "提交本轮"按钮依赖宿主的 window.zcode.sendFollowUpMessage 桥接：按钮点击无效或报错时（多见于旧版宿主），不反复重试，也不再升级问题——面板降级为纯展示（右栏结论仍随聊天里的回答更新），改让用户直接在聊天中打字回答本轮选项，后续轮次沿用该方式。

• 仅当需要面板之外的复杂可视化（图表、地图等）时，才加载 visualize skill。

• 消除"会话中断/结束"的错觉：①每轮题干标注轮次进度（如"第 2/4 轮"）；②每轮答案返回后立即继续，先给累积结论快照（当前报告的浓缩版），再进入下一轮；③未到最后一轮不用"完成/总结"等收尾措辞，并明确说"答完自动进入下一轮"；④最后一轮复述全案并明确宣布"澄清完成，以下是最终报告"。

• 用复述确认技巧：每轮结束后用一两句话总结理解，请用户确认或纠正。
• 用户答非所问或偏离时，温和拉回当前维度；轨道外问题（技术选型、实现方案等）一句话登记进未决项并上报 z-flow-kickoff 停车场（未被编排时自管，随报告附录 A 移交），本轮不展开。
• 若发现需求本身矛盾，明确指出冲突并请用户裁决，不替用户做决定。
• 宿主无 AskUserQuestion 类工具时，退化为纯文本提问，但保持轮次节奏、进度标注与结论快照。

带 preview 的调用示例（节选，展示字段写法与"结论 + 影响"式 preview 内容）：

{
  "questions": [{
    "question": "第 2/4 轮：数据质量要求到什么程度？答完自动进入下一轮",
    "header": "数据质量",
    "options": [
      { "label": "标注验收即可", "description": "成本最低，适合探索期",
        "preview": "报告将记录：\n· 质量 = 单次标注验收\n· 验收口径 = 抽检通过率\n\n影响：成本最低，适合探索期" },
      { "label": "抽样质检 + SLA", "description": "质检成本上升，需写明比例与时效",
        "preview": "报告将记录：\n· 质量 = 抽检 + SLA，需写明抽检比例与时效\n\n影响：质检成本上升，SLA 承诺写入验收" }
    ]
  }]
}

与 z-系列的关系

z-flow-kickoff（编排：开场协议→契约→横幅→交接→续跑）
   └─ z-pyramid(拆解) → z-clarify(本 skill：澄清→登记册) ⇄ z-chain(生态/干系人事实)
                              ↓
                       z-assess(四维+风险+假设 → Go/No-Go)
                              ↓ Go
                       z-init(工程文档基线化) → 下游 spec/开发（松耦合，AGENTS.md 契约）

• z-pyramid：大需求拆子问题（场景 A）、报告结论检验（纵向三规则）——文首与输出处已引用；未安装时按 MECE 内置退化。
• z-chain：维度 4/6 的结构与事实底座；建图时机见维度 6；未安装时三问内置退化。
• z-assess：澄清收口后用户需要判断"值不值得做"时交给它；本 skill 不下评估结论。
• z-init：项目确认后消费报告与登记册，落成 SRS 与跟踪矩阵。
• 各 skill 相互独立、按需组合；联动方未安装时按本文件内的退化规则执行。

边界

• 本 skill 不做：技术方案设计、工作量评估、代码实现、可行性评估结论（Go/No-Go 属 z-assess，维度 10 只收集风险事实与边界，不下判断）。
• "方案评审"场景下只澄清需求侧问题（目标、边界、验收标准），不评审技术方案本身的优劣。
• 不虚构信息：用户未提供的内容，标注为"待确认"，不自行脑补；登记册"无来源不入册"。
• 不替用户拍板：方向、优先级、范围取舍都需用户明确，遇到冲突引导用户决策。
• 保持语言与用户一致（中文需求用中文澄清，英文同理）。