| name | 507-grill |
| description | 实施前对齐的决策树追问（通用，代码/写作都用）。把一个改动/方案的每个决策分支沿依赖关系问到底；每轮只收集 frontier（前置条件已确定）的独立决策，有合适工具时批量收集，否则一次只问一个问题。需要用户决策时必须给出 2–5 个有真实权衡的候选并标出推荐项，边问边把术语/决策/经验沉淀进 doc。代码里沉淀进项目 doc，写作里把判断问透后另行落碎片。Use when user mentions 先对齐一下, 追问一下, 实施前对齐, 帮我把这个方案问透, 这个改动我先聊聊, 把方案问透, 决策对齐, 我们先聊聊, 对齐一下设计, 把决策树走一遍, 一个问题一个问题问, 拷问一下方案, 质疑一下这个设计, grill, pre-flight review, align before build, decision tree, interrogation. |
决策树追问（grill）
在真正动手改代码之前，用一轮结构化追问把计划问透：先与用户框定要解决的顶层分支，再在范围内按 frontier（当前可问边界） 推进——即所有前置条件已确定、可立刻询问的用户决策；其中互不影响的决策可由合适工具批量收集，没有合适工具时逐题问到底。每轮回答后重新计算 frontier；每走完一个分支收束固化一次，走完即结束。对齐过程中确定的术语当场沉淀进 doc/术语表.md（术语表），够格的决策记入 doc/决策档案/（架构决策记录）。
解决的核心问题是 misalignment（对齐失败）——agent 以为懂了，做出来才发现理解错了。先追问，再动手。
覆盖什么
- 一个具体改动 / 功能 / 方案实施前的对齐
- 把模糊需求追问成精确的决策
- 在提问前读取代码、运行既有测试或做最小只读/可丢弃验证，先把可查事实查清
- 顺便沉淀项目术语表和关键决策
不覆盖什么
- 结构化方案 / 计划文档起草 → 不在本 skill 范围
- 代码实现本身（对齐完交给正常开发流程）
- 不把 agent 应自行完成的设计、API（接口）细节、内部模块划分、参数命名、测试清单或工程验证方案交给用户决策；这些是对齐结论后的 agent 设计责任。
两者递进：507-grill（轻量对齐，分钟级）→ 落成方案文档（另一件事）。
核心纪律（不可违反）
- 按 frontier 推进依赖层：先识别当前 frontier（所有前置条件已确定、可立即询问的用户决策）。若其中只有一个问题，或没有合适的收集工具，一次只问一个问题，等用户回答后重新计算；若有合适工具，则将当前已知、彼此答案不会改变对方是否出现、题意或候选项的决策批量收集。绝不将依赖未决答案或未核实事实的问题提前混入。
- 需要用户决策时，给出 2–5 个真实候选并标出推荐项。每项用一行写清“适合什么 + 代价什么”；推荐项是其中一个候选，不是唯一视角。
- 候选必须对抗性成立：它们必须代表不同策略、优先级或权衡，至少主动检查一个能挑战推荐项的反向路径。不要从同一个推荐答案衍生轻微变体凑数；如果理性的协作者在不同优先级下不会真选某项，就删掉它。已被既有决策、代码事实或项目边界排除的路径不是候选——说明为何排除即可，不得为凑数重提。应主动检查“暂不做 / 延后验证”，但只有它确实合理时才列入。
- 先过事实与决策所有权闸门，再问用户：能通过代码、文档、既有共识、工程常识、运行既有测试或小型验证自行确定的，先验证并把证据带回对话，不把可查事实改写成用户选择题。环境事实未决时，只冻结依赖它的问题，其余 frontier 照常推进。API schema（模式）、参数命名、单次上限、模块边界、兼容策略、状态细节、测试接缝与工程验证默认由 agent 收口；只有会改变产品意图、权责边界、不可逆成本、体验取舍或风险承受的选择，才交给用户。若只有一个合理结论，直接说明判断并执行，不伪造候选。
- 纠错先于追问：发现概念混淆、重复已排除路径或将工程细节转交给用户时，立即停止当前决策树；重述已确认边界，撤回错误候选或未落地文档，自行收口受影响的工程设计。不得把修正自身理解变成新的用户选择题。
- 有界决策树（总上限）：追问开始前，先与用户框定本次对齐要解决的顶层分支（粗框、有边界即可）；后续追问在这个范围内走，每个分支沿依赖关系一个接一个问到底，不中途跳过；所有顶层分支走完即结束，这是整个对齐的总上限，不靠用户叫停。
- 阶段性收束（过程上限 + 固化记忆）：每走完一个顶层分支，强制收束一次——在对话里输出一块累积共识（见输出格式），把截至当前所有已确认分支的结论固化下来。这既是过程上限（单分支走完即固化、不无限下钻），也解决长对话的记忆衰减：共识不靠对话流记忆，靠这块最新、最全的锚点。
- 显式扩范围：追问中发现顶层分支范围外的相关问题，先停下来跟用户确认要不要纳入；纳入则更新范围清单继续走；不纳入则记成观察项留到对齐总结里，本次不展开。不偷偷扩成无限追问。
输出格式
三种输出对应三个阶段：开始前框定范围、过程中按分支收束、全部走完做总结。
框定范围（追问开始前）
## 本次对齐范围
顶层分支：
1. <分支一>
2. <分支二>
...
请确认，或增删。
追问（一个依赖层）
只在通过“决策所有权闸门”后使用本模板。若当前依赖层有多道已知且互不影响的问题，并且有合适的收集工具，可一次批量收集；否则用本模板一次只问一个问题。不要把 API（接口）字段、内部实现、测试路径、验证动作或已被排除的选项写进候选。
## 问题 N
<一个只有用户能决定的具体问题>
1. <候选一> —— <适合什么 + 代价什么>
2. <候选二> —— <适合什么 + 代价什么>
3. <候选三（若真实存在）> —— <适合什么 + 代价什么>
**我的推荐：** 选项 N；<一句判断和理由>。
**为什么现在问：** <这个问题会影响哪些后续分支>
收束（每走完一个顶层分支）
在对话里重写整块累积共识——按分支分组、带序号，让这块永远是最新、最全、最靠前的锚点，旧上下文被稀释也不影响：
## 当前共识（截至分支 K 完成）
### 分支 1：<分支名>
- <结论一>
- <结论二>
### 分支 2：<分支名>
- <结论一>
### 分支 K：<分支名>（本次新增）
- <结论一>
对齐总结（所有顶层分支走完）
一句话：已确认什么、有哪些观察项、建议下一步进入哪个工作流（直接实现 / 落成方案文档 / 备查 等）。
若用户只要求对齐、尚未明确授权实施，则在总结后先请其确认“共同理解已成立”，再动手；若原始请求已明确“对齐后直接实施”，无需重复设确认关口。
对齐时同步做的四件事
边追问边做，不是独立步骤：
- 挑战术语冲突：用户用的词若和
doc/术语表.md 现有定义冲突，当场指出——"术语表里 X 定义是 A，但你这里像在说 B，是哪个？"
- 锐化模糊语言：遇到模糊或过载的词，提出精确的规范术语——"你说的是'账户'，指 Customer（客户）还是 User（用户）？这俩是不同东西。"
- 造具体场景压测：讨论概念关系时，编造压测边界的场景，促使用户精确界定概念边界。
- 对照代码验证：用户描述某处怎么工作时，去代码里核对；发现矛盾就挑明——"代码里是整单取消，但你刚说支持部分取消，哪个对？"
边对齐边沉淀
对齐过程产出的东西分两类：会话级共识（够不上长期沉淀、但撑起本次对齐的判断）活在对话里的累积共识块，对齐结束即可清理；该长期留的东西走下面三个 doc 出口。够格进 ADR / 术语表 / 经验笔记的，当场从共识块里"提拔"到对应文件，不在共识块里重复堆积——共识块是暂存区，doc 出口是归宿。
术语 → doc/术语表.md
一个术语敲定就当场写进 doc/术语表.md，不攒着批量补。
doc/术语表.md 是纯粹的术语表，不沾任何实现细节——不是 spec（规格说明）、不是草稿本、不是决策仓库，只回答"这个项目里这个词精确指什么"。格式见附录。
决策 → doc/决策档案/
只有同时满足三条才记 ADR：
- 难逆转——事后改主意的成本很高。
- 无上下文会让人困惑——未来读者看到代码会问"为什么这么搞"。
- 有真实权衡——存在过真正的备选方案，你为特定理由选了这一个。
缺任何一条都不记。ADR 可以只有一段话，重点是"记录做了决定 + 为什么"，不是填模板。
做法 → doc/经验笔记.md
收"可改的做法与避坑经验"，回答"这事儿怎么做"。与术语表、决策档案按边界分工，不混用。
准入门槛：解决一个坑时，如果换一个无上下文的 agent 来会重走一遍，就值得记。不满足 ADR 三条（所以进不了决策档案）、也不是词的定义（所以进不了术语表），但下次还会用到的经验走这里。
条目格式：现象 + 做法 + 证据（日志路径 / commit / ADR 指向）。写不出证据 = 还没到值得记的程度。
维护方式：重复发生时在原条目追加证据，不新建条目。做法被推翻就改这条，不删（保留演进痕迹）。
文档结构约定
遵循项目既有目录，不另起 CONTEXT.md：
- 术语表：
doc/术语表.md（单文件，大多数项目够用）
- 决策记录：
doc/决策档案/0001-中文标题.md（顺序编号，标题用中文，项目术语沿用术语表规范叫法）；新增 / 更新 ADR 时同步 doc/决策档案/README.md 索引（编号 + 标题 + 一句话主旨）
- 经验笔记：
doc/经验笔记.md（单文件，条目用 markdown 列表）
- 惰性创建：没有
doc/术语表.md 就不建，第一个术语敲定时再建；doc/决策档案/、doc/经验笔记.md 同理。
启动姿势
当用户说"先对齐一下 / 追问一下 / grill"时：
- 先理解这次要做什么改动。
- 按 AGENTS.md 文档优先级读
doc/，掌握现有术语和已记录决策。
- 框定顶层分支：列出本次对齐要解决的顶层分支，请用户确认范围（这是总上限的依据）。
- 每次提问前先过“事实与决策所有权闸门”：能读代码、跑测试或做最小验证查清的事实先自行查；能由 agent 收口的工程细节立即自行设计；只有用户意图 / 边界 / 风险取舍进入问题列表。
- 在范围内按 frontier 追问，一个分支一个分支走：每轮仅收集前置条件已确定的独立决策；有合适工具时批量收集，否则一次只问一个问题；每轮回答后重新计算 frontier；每走完一个顶层分支，输出一块累积共识。
- 每敲定一个术语 / 决策，当场从共识块里"提拔"到对应 doc 文件。
- 所有顶层分支走完，agent 自行补全 API、实现切片和验证方案；给用户一句话总结对齐结果。仅当用户未在原始请求中明确授权实施时，再请其确认共同理解后进入实现或交接。
完成与接力
- 完成信号：顶层分支已走完；可查事实有证据，用户拥有的决策已确认，工程细节由 agent 收口；最新共识块没有互相冲突的旧结论。
- 产物：会话中的累积共识，以及够格时同步更新的术语表、决策档案或经验笔记。
- 候选出口：面向人的活动、培训、合作或项目方案进入
507-frame；具体产品需求需要耐久规格时进入 507-prd；需要追踪调查或执行时进入 507-issue；需要低成本观察后再定时进入 507-prototype；前提充分且已授权时直接实施；只需对齐时直接结束。
- 回退条件：发现项目事实仍不清楚时转
507-explore、507-research 或 507-prototype，带回证据后继续当前决策树。
附录：术语表格式（doc/术语表.md）
# {项目名} 术语表
{一两句话说明这是什么项目。}
## Language
**Order（订单）**：
客户发起的一次购买请求。
_Avoid_: Purchase、transaction
**Customer（客户）**：
下单的人或组织。
_Avoid_: Client、buyer、account
规则：
- 定义"它是什么"，不是"它做什么"，一到两句。
- 有同义词时挑最好的做主词，其余列入
_Avoid_（禁用词）。
- 只收项目特有概念；通用编程概念（timeout、错误类型、工具模式）即使大量使用也不收。
附录：ADR 格式（doc/决策档案/）
# {决策的短标题}
{1-3 句：背景是什么、决定了什么、为什么。}
就这样，可以只有一段。仅在"记录做了决定 + 为什么"有价值时才写。可选段落（Status / Considered Options / Consequences）只在确实有内容时加。文件名顺序编号：扫 doc/决策档案/ 取最大号 +1。
