intent-confirmation git:20260725.41a1808A

Immutable. This exact content is served forever at /api/v1/blob/5ebd930def8f27eb.

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

# 意图确认规范

## 概述

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

1. **读懂用户真正要什么**
2. **用反问补全缺失信息**
3. **帮用户把模糊想法梳成可写代码的思路**
4. **在 R&K 关键节点把门禁结论落盘**

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

## 核心原则

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

## 三步工作法

```text
用户提出需求
    ↓
Step A · 理解转述
  - 用自己的话写成可执行目标
  - 标出已假设的默认值
  - 标出明显边界（做 / 暂不做）
    ↓
Step B · 反问梳理（编码思路）
  - 针对缺口提 2–5 个关键问题
  - 覆盖：目标验收、范围、触点、路径取舍、约束、风险
  - 每问尽量带推荐默认
    ↓
Step C · 收敛确认
  - 合并用户回答，输出「编码思路小结」
  - 请用户确认或修正
  - 通过 → 执行 / 进入下一 Spec 阶段
  - 不通过 → 回到 B 补问，不开工
```

**禁止**：只做「是这个意思吗？是/否」就结束，却不帮用户想清怎么写。  
**禁止**：反问变成技术审讯（一次抛十个实现细节）。  
**允许**：用户说「你定/按你说的」时，采用已声明的推荐默认并写进小结。

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

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

| 维度 | 反问目的 | 示例问法 |
|------|----------|----------|
| **目标与验收** | 怎样算做完 | 「上线标准是单测通过，还是要有可演示接口？」 |
| **范围边界** | 做/不做 | 「本次只改后端，前端先不动，可以吗？」 |
| **用户/调用链** | 谁触发、输入输出 | 「是 SSE 流式返回，还是 REST 一次返回？」 |
| **代码触点** | 改哪些模块 | 「我倾向动 `services/report_*.py`，是否还有别的入口？」 |
| **实现路径** | 方案分叉 | 「A 最小补丁 / B 抽公共层，你更倾向？我建议 A」 |
| **数据与状态** | 存哪、兼容性 | 「是否要兼容旧缓存 key？」 |
| **约束** | 时间/兼容/性能 | 「必须保持现有 API 字段不变吗？」 |
| **风险与回滚** | 怕踩什么坑 | 「若命中失败，是降级查库还是直接报错？」 |
| **验证方式** | 怎么证明对了 | 「用现有 pytest，还是要补一条 e2e？」 |
| **优先级切片** | MVP vs 完整 | 「先做可运行 MVP，细节二期？」 |

### 好的反问

- 绑定用户原话中的模糊点
- 给出 2–4 个互斥选项 + 推荐默认
- 帮用户做取舍，而不是要用户从零设计
- 问完能直接写出 plan 或动手步骤

### 差的反问

- 「你有没有想过用设计模式？」类空泛题
- 重复用户已说清的内容
- 一次要用户写整份技术方案
- 与当前阶段无关（需求对齐时追问 commit message 格式）

## 触发条件

### 需要走本规范

| 场景 | 说明 | 示例 |
|------|------|------|
| **抽象需求** | 描述模糊 | 「优化一下这个功能」 |
| **思路未成形** | 用户知道痛点但不知怎么改 | 「这里总是重复代码，想整理下」 |
| **设计决策** | 架构/方案分叉 | 「重构用户认证模块」 |
| **多义表达** | 多种解读 | 「更新文档」 |
| **大范围影响** | 跨模块/协议 | 「统一错误处理」 |
| **多步骤任务** | 复杂链路 | 「实现用户注册流程」 |
| **R&K 门禁** | 阶段切换 | 需求对齐、批准实现、归档/PR |
| **破坏性操作** | 高风险 | 清库、强推、改生产配置 |

### 可跳过或极简

| 场景 | 处理 |
|------|------|
| 明确简单任务 | 直接做（如「运行测试」） |
| 已确认 Spec | 按 plan 执行，不重开需求讨论 |
| 信息查询 | 直接答 |
| 单点小修 | 直接改 |
| 用户豁免 | 「直接做，不用问」→ 执行，但破坏性操作仍要拦 |

## 运行时适配

### OMP（推荐）

用 `ask` 做结构化反问与确认：

- 每题 `id` / `question` / `options`（2–5 项）
- **不要**手写 Other（UI 自带）
- `recommended`：你的默认建议
- `multi: true`：范围多选（模块、验收项）
- 可分两轮：先「理解 + 关键取舍」，再「编码思路小结确认」
- headless：改用文本模板，等用户下一条消息

**反问示例（梳理实现路径）：**

```text
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
    }
  ]
})
```

**收敛确认示例：**

```text
ask({
  questions: [{
    id: "approach_ok",
    question: "编码思路小结：1) 只改后端 publish 管线 2) 命中/未命中各打结构化日志 3) 补单测 4) 不改 API。按此开始？",
    options: [
      { label: "按此开始" },
      { label: "基本可以，我补充一点" },
      { label: "不对，重梳思路" }
    ],
    recommended: 0
  }]
})
```

### Claude Code / 其他

- 有原生提问 UI 则用；否则用下方文本模板
- 不要写死 `AskUserQuestion` / `TodoWrite` 等工具名

## 文本模板

### A. 理解转述

```text
我先用自己的话理解你的目标：
- 目标：…
- 范围：…（默认：…）
- 不做：…

我的默认假设：…
```

### B. 反问梳理

```text
为把编码思路定清楚，需要你拍板：
1. [验收] …？我建议 …
2. [路径] A … / B …？我建议 A，因为 …
3. [范围] …？

你可以直接选建议项，或改条件。
```

### C. 编码思路小结（确认用）

```text
根据你的反馈，编码思路如下：
1. 入口/触点：改哪些文件或模块
2. 步骤顺序：先 … 再 … 最后 …
3. 关键取舍：选了 A 而非 B，因为 …
4. 验收：怎样算完成
5. 风险：…；回滚/降级：…

确认按此执行吗？
```

## R&K Flow 集成

| 时机 | 谁发起 | 反问/确认重点 | 落盘 |
|------|--------|----------------|------|
| `spec-start` 阶段一 | TeamLead | 目标、范围、分类、分支、**实现思路粗纲** | Gate Decisions + Next Action；可把思路要点写入 team-context 备注 |
| plan + test-plan 完成 | TeamLead | 是否批准实现（不再重梳需求，除非用户改需求） | Gate：设计/测试计划确认 |
| 修复循环前 | TeamLead | Loop Budget + 是否同意按诊断修 | Loop Budget + Gate |
| `spec-end` 前 | TeamLead/ender | 归档/提交/PR | end-report + Gate |
| `spec-update` | TeamLead | 更新范围是否仍在原 Spec | updater + Gate |

规则：

- **阶段一必须反问梳理**，不能只「需求 ok 吗」
- TeamLead 对用户；子角色默认不直接连环问用户
- 已批准的 `writer/plan.md` 执行期不重开需求研讨会，除非需求变更
- 反问得到的「编码思路小结」应能直接喂给 spec-explorer / spec-writer 作为输入

### 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 阶段匹配  

### 差

- 只复读 + 「是吗？」  
- 反问空泛或过多  
- 替用户隐瞒风险假设却不声明  
- 确认完不落盘、下游角色收不到思路小结  

## 与其他 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 改门禁  
- headless 硬调交互 UI 后卡住不降级  

## 后续动作

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