| disable-model-invocation | true |
| name | intent-confirmation |
| description | 当用户的请求在执行前需要澄清目标、边界或实现思路时使用：需求抽象、涉及架构 或设计决策、影响范围大、存在多种实现路径、可能修改重要文件、用户思路尚不清晰， 或用户明确要求先确认。也用于 R&K Flow 阶段门禁（需求对齐、plan/test-plan 确认、 归档/提交前确认）。本 skill 要求提问前先交代「我做了什么、发现了什么、要你决策 什么」，再复述理解并主动反问，帮用户补全信息并梳理代码编写思路，而不是只做 「是/否」确认，也不是不给背景就抛问题。不要用于简单问答、只读查询、明确的 小修小改、已确认 Spec 的直接执行，或用户已明确表示「直接做、不用问」。
|
意图确认规范
概述
本 Skill 定义 Agent 在执行任务前与用户对齐意图的标准流程。目标不仅是「避免理解偏差」，更是：
- 让用户知道你问的是什么 — 提问必须自带上下文
- 读懂用户真正要什么
- 用反问补全缺失信息
- 帮用户把模糊想法梳成可写代码的思路
- 在 R&K 关键节点把门禁结论和决策理由落盘
确认通过后，用户应对「目标 / 范围 / 关键取舍 / 大致实现路径」有共同画面；Agent 再动手。
核心原则
- 先交代情境，再提问 — 用户不该为了理解你的问题去猜你刚做了什么
- 先理解，再反问，后确认 — 不是复读原话，也不是上来就写代码
- 反问为了梳理思路 — 问题应推动用户想清：改哪里、先做什么、成功长什么样
- 短而可执行 — 复述用可落地条目；反问 2–5 个阻塞点，不审讯
- 带假设反问 — 每个问题尽量附「我的默认理解是 X，对吗？」，降低用户负担
- 少问精问 — 仓库/上下文能推断的不问；只问影响设计与编码路径的点
- 运行时中立 — 优先结构化提问（OMP:
ask）；无 UI 时用文本
- 门禁与决策落盘 — 门禁结论写入
lead/team-context.md 的 Gate Decisions；决策的选项、结论和理由写入 Decision Log
四步工作法
用户提出需求
↓
Step 0 · 情境交代（Situation Brief）【强制前置】
- 我做了什么：读了哪些文件、跑了什么命令、查了什么
- 我发现了什么：与提问直接相关的事实和结论
- 卡在哪：为什么这件事我不能自己定
- 要你决策什么：一句话点题
↓
Step A · 理解转述
- 用自己的话写成可执行目标
- 标出已假设的默认值
- 标出明显边界（做 / 暂不做）
↓
Step B · 反问梳理（编码思路）
- 针对缺口提 2–5 个关键问题
- 覆盖：目标验收、范围、触点、路径取舍、约束、风险
- 每问尽量带推荐默认
↓
Step C · 收敛确认
- 合并用户回答，输出「编码思路小结」
- 请用户确认或修正
- 通过 → 落盘 Decision Log → 执行 / 进入下一 Spec 阶段
- 不通过 → 回到 B 补问，不开工
禁止：不给情境直接抛问题，让用户猜「你在问什么东西」。
禁止：只做「是这个意思吗？是/否」就结束，却不帮用户想清怎么写。
禁止：反问变成技术审讯（一次抛十个实现细节）。
允许：用户说「你定/按你说的」时，采用已声明的推荐默认并写进小结与 Decision Log。
Step 0 · 情境交代（必读）
用户最常见的抱怨是「Agent 直接问我问题，我不知道他在问什么」。根因是提问缺少前置状态同步。任何提问前，先输出四段极短情境，每段 1–3 行：
| 段 | 内容 | 反例 |
|---|
| 已做（Did） | 具体动作 + 对象：读了 x.py、跑了 pytest tests/y、查了配置 | 「我调研了一下」（没说查了什么） |
| 发现（Found） | 与本次提问因果相关的事实/结论，带证据位置 | 「有点问题」（没说什么问题、在哪） |
| 卡点（Blocked） | 为什么这是用户的决策而非你能定的默认 | 直接跳到问题，不说为何要问 |
| 求决策（Need） | 一句话点明要拍板的事 | 「你怎么看？」 |
规则：
- 有证据：
Found 的每条结论尽量带文件路径、行号、命令名或报错关键字。
- 可省不省：即使只有一个问题，也要有
Did + Need；Found/Blocked 无实质内容时可各一行说明。
- 不复述全文：情境总长控制在 10 行内；细节放已落盘的产物路径，让用户按需查。
- 结构化提问同样适用：
ask 的 UI 只承载选项，情境写在 ask 之前的正文里；不要把整段情境塞进 question 字段。
- 零调查时说明：如果还没做任何调查就要提问（如刚接到需求），
Did 写「尚未动代码，仅读取你的需求描述」，不要编造调查动作。
情境交代模板
【已做】
- 读了 services/report_publish.py:120-180、config/cache.yaml
- 跑了 pytest tests/test_publish.py（12 passed）
【发现】
- 缓存命中/未命中两条分支都没有日志，命中率无法观测（report_publish.py:143、:151）
- 现有 logger 是纯文本格式，没有结构化字段
【卡点】
- 加结构化日志会改动现有 logger 输出格式，可能影响你们已有的日志采集，这不是我能替你定的
【要你决策】
- 日志格式：沿用纯文本，还是切 JSON 结构化？
紧接其后才是 Step A 的理解转述与 Step B 的反问。
情境交代质量自检
提问前自问三条，任一为「否」就先补情境再问：
- 用户只看我这条消息，能否明白我为什么问这个问题？
- 我给出的每个选项，用户能否判断它的后果？
- 我是否把「能自己查到的事实」错当成了「要用户回答的问题」？
反问维度（编码思路清单）
按任务需要选用，不必全问。优先问阻塞编码的项：
| 维度 | 反问目的 | 示例问法 |
|---|
| 目标与验收 | 怎样算做完 | 「上线标准是单测通过，还是要有可演示接口？」 |
| 范围边界 | 做/不做 | 「本次只改后端，前端先不动，可以吗？」 |
| 用户/调用链 | 谁触发、输入输出 | 「是 SSE 流式返回，还是 REST 一次返回？」 |
| 代码触点 | 改哪些模块 | 「我倾向动 services/report_*.py，是否还有别的入口？」 |
| 实现路径 | 方案分叉 | 「A 最小补丁 / B 抽公共层，你更倾向？我建议 A」 |
| 数据与状态 | 存哪、兼容性 | 「是否要兼容旧缓存 key？」 |
| 约束 | 时间/兼容/性能 | 「必须保持现有 API 字段不变吗？」 |
| 风险与回滚 | 怕踩什么坑 | 「若命中失败，是降级查库还是直接报错？」 |
| 验证方式 | 怎么证明对了 | 「用现有 pytest，还是要补一条 e2e？」 |
| 优先级切片 | MVP vs 完整 | 「先做可运行 MVP，细节二期？」 |
好的反问
- 绑定用户原话中的模糊点
- 给出 2–4 个互斥选项 + 推荐默认
- 帮用户做取舍，而不是要用户从零设计
- 问完能直接写出 plan 或动手步骤
差的反问
- 「你有没有想过用设计模式？」类空泛题
- 重复用户已说清的内容
- 一次要用户写整份技术方案
- 与当前阶段无关（需求对齐时追问 commit message 格式）
- 无情境裸问：「用 A 还是 B？」但没说 A/B 是什么、你为何在这里遇到分叉
触发条件
需要走本规范
| 场景 | 说明 | 示例 |
|---|
| 抽象需求 | 描述模糊 | 「优化一下这个功能」 |
| 思路未成形 | 用户知道痛点但不知怎么改 | 「这里总是重复代码，想整理下」 |
| 设计决策 | 架构/方案分叉 | 「重构用户认证模块」 |
| 多义表达 | 多种解读 | 「更新文档」 |
| 大范围影响 | 跨模块/协议 | 「统一错误处理」 |
| 多步骤任务 | 复杂链路 | 「实现用户注册流程」 |
| R&K 门禁 | 阶段切换 | 需求对齐、批准实现、归档/PR |
| 破坏性操作 | 高风险 | 清库、强推、改生产配置 |
可跳过或极简
| 场景 | 处理 |
|---|
| 明确简单任务 | 直接做（如「运行测试」） |
| 已确认 Spec | 按 plan 执行，不重开需求讨论 |
| 信息查询 | 直接答 |
| 单点小修 | 直接改 |
| 用户豁免 | 「直接做，不用问」→ 执行，但破坏性操作仍要拦 |
运行时适配
OMP（推荐）
用 ask 做结构化反问与确认。调用 ask 前必须先在正文输出 Step 0 情境交代，ask 只承载选项：
-
每题 id / question / options（2–5 项）
-
不要手写 Other（UI 自带）
-
recommended：你的默认建议
-
multi: true：范围多选（模块、验收项）
-
可分两轮：先「理解 + 关键取舍」，再「编码思路小结确认」
-
headless：改用文本模板，等用户下一条消息
-
每个 option 的 description 写清「选了它会发生什么」，不要只写方案名
反问示例（梳理实现路径）：
先输出情境（正文）：
【已做】读了 services/report_publish.py 的 publish 管线，跑通现有 pytest
【发现】命中/未命中两条分支都无日志；现有 logger 为纯文本
【卡点】改 logger 格式会影响既有日志采集，需要你拍板
【要你决策】验收标准、实现路径、改动范围
再发起结构化提问：
ask({
questions: [
{
id: "goal",
question: "我理解目标是：报告缓存命中时写出可检索日志。成功标准选哪个？",
options: [
{ label: "单测覆盖关键分支即可", description: "推荐，改动小" },
{ label: "单测 + 本地手跑一条请求看日志" },
{ label: "还要 e2e / 线上可观测字段" }
],
recommended: 0
},
{
id: "path",
question: "实现路径我建议最小补丁。你选？",
options: [
{ label: "A 最小补丁", description: "只在 publish 管线命中/未命中处打日志" },
{ label: "B 抽统一 logging helper", description: "多点复用，改动面更大" },
{ label: "先只写 plan，不改代码" }
],
recommended: 0
},
{
id: "scope",
question: "本次范围？",
options: [
{ label: "仅后端", description: "推荐" },
{ label: "后端 + SSE 事件字段" },
{ label: "后端 + 文档/注释" }
],
recommended: 0,
multi: false
}
]
})
收敛确认示例：
ask({
questions: [{
id: "approach_ok",
question: "编码思路小结：1) 只改后端 publish 管线 2) 命中/未命中各打结构化日志 3) 补单测 4) 不改 API。按此开始？",
options: [
{ label: "按此开始" },
{ label: "基本可以，我补充一点" },
{ label: "不对，重梳思路" }
],
recommended: 0
}]
})
Claude Code / 其他
- 有原生提问 UI 则用；否则用下方文本模板
- 不要写死
AskUserQuestion / TodoWrite 等工具名
文本模板
0. 情境交代（提问前强制）
【已做】…（读了哪些文件 / 跑了什么命令 / 查了什么）
【发现】…（与提问相关的事实，带路径或报错关键字）
【卡点】…（为什么需要你定）
【要你决策】…（一句话）
A. 理解转述
我先用自己的话理解你的目标：
- 目标：…
- 范围：…（默认：…）
- 不做：…
我的默认假设：…
B. 反问梳理
为把编码思路定清楚，需要你拍板：
1. [验收] …？我建议 …
2. [路径] A … / B …？我建议 A，因为 …
3. [范围] …？
你可以直接选建议项，或改条件。
C. 编码思路小结（确认用）
根据你的反馈，编码思路如下：
1. 入口/触点：改哪些文件或模块
2. 步骤顺序：先 … 再 … 最后 …
3. 关键取舍：选了 A 而非 B，因为 …
4. 验收：怎样算完成
5. 风险：…；回滚/降级：…
确认按此执行吗？
R&K Flow 集成
| 时机 | 谁发起 | 情境交代要点 | 反问/确认重点 | 落盘 |
|---|
spec-start 阶段一 | TeamLead | 读了哪些既有代码/文档、当前仓库与分支状态 | 目标、范围、分类、分支、实现思路粗纲 | Gate Decisions + Decision Log + Next Action |
| plan + test-plan 完成 | TeamLead | plan/test-plan 的核心方案与关键取舍摘要、未解风险 | 是否批准实现（不再重梳需求，除非用户改需求） | Gate：设计/测试计划确认 + Decision Log |
| 修复循环前 | TeamLead | 失败用例、已定位的根因或未定位的原因 | Loop Budget + 是否同意按诊断修 | Loop Budget + Gate + Decision Log |
| 循环触上限升级 | TeamLead | 已用轮数、每轮进展、仍失败的具体项 | 加预算 / 改方案 / 暂停 | Loop Budget + Decision Log |
spec-end 前 | TeamLead/ender | 交付内容、测试结论、遗留问题 | 归档/提交/PR | end-report + Gate + Decision Log |
spec-update | TeamLead | 本次更新触发原因、与原 Spec 的差异 | 更新范围是否仍在原 Spec | updater + Gate + Decision Log |
规则：
- 每个门禁提问都必须带 Step 0 情境交代，禁止只发一句「确认吗」
- 阶段一必须反问梳理，不能只「需求 ok 吗」
- TeamLead 对用户；子角色默认不直接连环问用户
- 子角色向 TeamLead 上报时也按
Did / Found / Blocked / Need 四段写，TeamLead 才能不改写就转述给用户
- 已批准的
writer/plan.md 执行期不重开需求研讨会，除非需求变更
- 反问得到的「编码思路小结」应能直接喂给 spec-explorer / spec-writer 作为输入
- 用户拍板后立即在
lead/team-context.md 的 Decision Log 追加一行，记录 options（当时给的选项）、decision、rationale、decided_by: user；被否决的选项不要丢，它是后续复盘的关键上下文
spec-start 阶段一最小问题集
至少覆盖（可合并进 2–4 个 ask 题）：
- 任务目标一句话 + 验收标准
- 范围（模块/做不做前端或文档）
- 实现倾向（最小补丁 / 重构 / 先调研）
- Git：新分支 / 当前分支 / 先不建分支
确认后的行为
用户确认思路正确
- 简短回执
- 复杂任务用
todo（或等价工具）拆步
- 进入对应流程（explore/write/execute…）
- 把编码思路小结交给下游角色，避免 explorer/writer 重新猜
用户补充或纠正
- 合并进小结
- 若仍缺阻塞信息 → 再反问一轮（收敛，不发散）
- 再确认后执行
取消 / 超时
ask 取消：不执行- 超时采用 recommended：必须声明「已按推荐项 X」，允许用户立刻推翻
质量标准
好
- 用户只看提问这条消息，就知道你做了什么、为什么问
- 用户离开对话时比进来时更清楚怎么写
- 有明确触点、步骤、验收、不做列表
- 反问带默认建议，选项带后果说明
- 与当前 R&K 阶段匹配
- 决策拍板后
Decision Log 有对应行
差
- 不给情境裸问，用户看不懂在问什么
- 只复读 + 「是吗？」
- 反问空泛或过多
- 替用户隐瞒风险假设却不声明
- 确认完不落盘、下游角色收不到思路小结
- 决策做了却不进
Decision Log，后续无从复盘
与其他 Skill 的协作
| Skill | 协作 |
|---|
spec-start | 阶段一强制本规范（理解+反问+确认） |
spec-explore | 输入含已确认范围与思路要点，避免空泛探索 |
spec-write | 基于确认后的思路写 plan，不另起炉灶改目标 |
spec-test | 验收标准来自确认结果 |
spec-execute | 已确认 plan → 直接实现 |
spec-debug | 修前确认诊断；可轻量反问复现条件 |
spec-end / spec-update | 结束与小迭代门禁 |
exp-reflect | 长期偏好可在收尾沉淀 |
反模式
- 裸问：不交代情境直接抛问题，用户不知道在问什么
- 审讯式连问，无推荐默认
- 选项只给方案名，不说选了会发生什么
- 把能自己查的事实包装成问题丢给用户
- 用户思路不清时直接开写，导致返工
- 用静默假设代替反问（尤其是 API 兼容、数据迁移、范围）
- 子 Agent 绕过 TeamLead 改门禁
- 决策不落
Decision Log，或只记结论不记被否决的选项和理由
- headless 硬调交互 UI 后卡住不降级
后续动作
- 新 Spec → 继续
/spec-start 后续阶段
- 小迭代 →
/spec-update
- 已有确认 plan →
/spec-execute
- 纯沟通澄清 → 输出思路小结后结束或按用户下一步做
