intent-confirmation

disable-model-invocation	true
name	intent-confirmation
description	当用户的请求在执行前需要澄清目标、边界或实现思路时使用：需求抽象、涉及架构 或设计决策、影响范围大、存在多种实现路径、可能修改重要文件、用户思路尚不清晰， 或用户明确要求先确认。也用于 R&K Flow 阶段门禁（需求对齐、plan/test-plan 确认、 归档/提交前确认）。本 skill 要求提问前先交代「我做了什么、发现了什么、要你决策 什么」，再复述理解并主动反问，帮用户补全信息并梳理代码编写思路，而不是只做 「是/否」确认，也不是不给背景就抛问题。不要用于简单问答、只读查询、明确的 小修小改、已确认 Spec 的直接执行，或用户已明确表示「直接做、不用问」。

意图确认规范

概述

本 Skill 定义 Agent 在执行任务前与用户对齐意图的标准流程。目标不仅是「避免理解偏差」，更是：

1. 让用户知道你问的是什么 — 提问必须自带上下文
2. 读懂用户真正要什么
3. 用反问补全缺失信息
4. 帮用户把模糊想法梳成可写代码的思路
5. 在 R&K 关键节点把门禁结论和决策理由落盘

确认通过后，用户应对「目标 / 范围 / 关键取舍 / 大致实现路径」有共同画面；Agent 再动手。

核心原则

1. 先交代情境，再提问 — 用户不该为了理解你的问题去猜你刚做了什么
2. 先理解，再反问，后确认 — 不是复读原话，也不是上来就写代码
3. 反问为了梳理思路 — 问题应推动用户想清：改哪里、先做什么、成功长什么样
4. 短而可执行 — 复述用可落地条目；反问 2–5 个阻塞点，不审讯
5. 带假设反问 — 每个问题尽量附「我的默认理解是 X，对吗？」，降低用户负担
6. 少问精问 — 仓库/上下文能推断的不问；只问影响设计与编码路径的点
7. 运行时中立 — 优先结构化提问（OMP: ask）；无 UI 时用文本
8. 门禁与决策落盘 — 门禁结论写入 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 的反问。

情境交代质量自检

提问前自问三条，任一为「否」就先补情境再问：

1. 用户只看我这条消息，能否明白我为什么问这个问题？
2. 我给出的每个选项，用户能否判断它的后果？
3. 我是否把「能自己查到的事实」错当成了「要用户回答的问题」？

反问维度（编码思路清单）

按任务需要选用，不必全问。优先问阻塞编码的项：

维度	反问目的	示例问法
目标与验收	怎样算做完	「上线标准是单测通过，还是要有可演示接口？」
范围边界	做/不做	「本次只改后端，前端先不动，可以吗？」
用户/调用链	谁触发、输入输出	「是 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 题）：

1. 任务目标一句话 + 验收标准
2. 范围（模块/做不做前端或文档）
3. 实现倾向（最小补丁 / 重构 / 先调研）
4. Git：新分支 / 当前分支 / 先不建分支

确认后的行为

用户确认思路正确

1. 简短回执
2. 复杂任务用 todo（或等价工具）拆步
3. 进入对应流程（explore/write/execute…）
4. 把编码思路小结交给下游角色，避免 explorer/writer 重新猜

用户补充或纠正

1. 合并进小结
2. 若仍缺阻塞信息 → 再反问一轮（收敛，不发散）
3. 再确认后执行

取消 / 超时

• 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 后卡住不降级

后续动作

1. 新 Spec → 继续 /spec-start 后续阶段
2. 小迭代 → /spec-update
3. 已有确认 plan → /spec-execute
4. 纯沟通澄清 → 输出思路小结后结束或按用户下一步做