技能grill-with-docs

grill-with-docs

通过持续追问来打磨方案或设计，并在过程中同步产出文档（ADR 和术语表）。

Grill with Docs —— 拷问式方案评审，顺手产出 ADR 与术语表

Grill with Docs 是一个"边追问、边写文档"的方案评审技能：它对一份计划或设计发起持续、不留情面的追问，逼出其中的模糊假设与概念歧义，并在对话过程中同步沉淀出架构决策记录（ADR）和领域术语表（Glossary）。

它的定位不是替你写代码，也不是替你拍板，而是让你在被追问的过程中自己想清楚，并且把想清楚的结果直接留成可检索、可版本控制的文档。该技能被设置为手动触发（disable-model-invocation: true），只在你想被拷问的时候启动。

技术方案评审前的自我拷问 方案文档写完了，但心里清楚有几处是"先这么写着"。在提交评审或动手实现之前启动它，用一轮高强度追问把边界条件、失败模式、被放弃的备选方案逐一摊开，避免在会上被问倒。
新项目或新模块的领域建模 需求里混着"订单""工单""任务"这类叫法相近的概念，团队里每个人理解还不一样。技能在追问的同时捕捉术语歧义，统一命名并产出术语表，让后续的代码、文档、沟通有共同语言。
重构或接手遗留系统前的决策梳理 既有架构为什么长成这样，往往散落在聊天记录、PR 评论和离职同事的记忆里。通过追问把历史决策重新讲一遍，并落成 ADR，新加入的人不必再从代码反推设计意图。

高强度追问（Relentless Interview） 不一次性抛出问题清单，而是沿着你的回答继续深挖：这个假设在什么条件下不成立？失败时会发生什么？为什么不选另一个方案？追问会一直持续到关键分歧点被显式地做出取舍为止。
同步生成架构决策记录（ADR） 每当你真正做出一个取舍，技能就把"背景—选项—决定—后果"整理成一条 ADR。文档是访谈的副产品，不需要事后凭记忆补写，因此更贴近真实决策过程。
产出领域术语表（Glossary / Domain Model） 在对话中一旦发现同一个词被用于两种含义，或同一个概念有多种叫法，技能会当场追问并要求收敛，最终形成一份统一定义的术语表，作为项目后续沟通的基准。

实现上，该技能本身很薄：它会分别调用 grilling（追问）和 domain-modeling（领域建模）两个子技能各一次，由它们承担具体的追问与建模工作。

不会。它被设置为 disable-model-invocation: true，只能由你手动触发，不会在你正常编码或聊天时自行启动。这是刻意的设计——拷问式评审的体验并不轻松，应当由你主动选择何时接受它。

不会。技能的产出是问题和文档：代码与方案由你自己修改，它负责把隐含假设问出来、把结论记下来。因此它适合在方案定稿前使用，而不是当作自动化重构工具。

保存在你的项目仓库中，随代码一起做版本控制，而不是停留在聊天记录里。具体目录通常由你的项目约定决定（常见做法是放在 docs/ 下）。也正因如此，团队成员可以通过 Git 历史看到每个决策是在什么背景下做出的。

头脑风暴偏向发散——从一个模糊想法出发，探索可能性、拓宽方案空间；Grill with Docs 偏向收敛与检验——默认你已经有了一份方案，任务是找出它的漏洞并迫使你做出取舍。实践中两者可以串联：先发散得到候选方向，再用追问把选定的方向夯实。

取决于你想留下多少决策痕迹。个人项目往往"自己记得就行"，ADR 的收益有限；但如果你经常隔几个月回到自己的项目、想不起当初为什么这么设计，那术语表和 ADR 的价值就会显现出来。它同样适合用来检验自己是否真的想清楚了。

至少需要一份可以讨论的方案或设计描述，哪怕只是几段文字。材料越具体，追问越有针对性；如果只有一句"我想做个 X"，技能会先花大量轮次帮你把问题本身定义清楚。