用文档拷问

它的作用¶

grill-with-docs 会就某个计划或设计对你进行访谈，直到你和 智能体 对它有共同理解，并在过程中将术语和艰难决策写入你的仓库。它执行的是与 grill-me 相同的访谈（一轮问题，然后等待，再下一轮），只是指向一个代码库。

它是 有状态 的。其他所有审问技能都把 会话 留在你的脑子里；这个则把文件留在磁盘上。当一个术语被确定时，技能会立即将其写入 GLOSSARY.md，而不是最后批量写入。当一个决策通过三个关卡时，技能会将其写成一个 ADR。这就是全部区别，它也是人们在使用该技能时遇到大多数麻烦的原因。这些产物是真实仓库中的真实文件，因此当你期望它们存在时它们可能缺失，当多人写入它们时它们可能产生偏差。

何时使用¶

你通过输入 /grill-with-docs 来调用它，智能体不会主动使用它。

在仓库中，当变更刚开始、计划仍然模糊、相关事物的术语尚未确定时，使用它。它是单会话工具。你需要哪种审问技能取决于你面前有什么：

wayfinder 的区分关键在于会话数量：/grill-with-docs 用于单会话规划，/wayfinder 用于多会话规划。

前提条件¶

该技能会写入你的仓库，因此你需要处于一个可以安全写入的位置。已确定的术语会写入根目录的 GLOSSARY.md 术语表，或者如果根目录的 GLOSSARY-MAP.md 将仓库标记为多上下文，则写入相应上下文的 GLOSSARY.md。决策写入 docs/adr/。该技能只在需要时创建这两者。在第一个术语或决策敲定之前，什么都不会存在，因此你无需提前设置任何内容。

它还需要另外两个技能存在，因为它自己的 SKILL.md 只有一行，并委托给它们。grilling 提供访谈，domain-modeling 提供写作。只安装 grill-with-docs 会得到一个无法工作的技能。

书面记录¶

一次会话会产生三样东西，但它们并不等价。

第三行是最容易让人误解的地方。GLOSSARY.md 只是一个术语表。它不包含实现细节、不包含 规范，也不包含临时笔记。ADR 需要同时满足全部三个条件，因此大多数决策不符合条件，大多数会话也不会产生 ADR。一次只产生更清晰术语表且零 ADR 的会话是符合设计的，但这意味着你们达成的大部分内容只存在于你们达成它的那个 上下文窗口 中。把同样的对话交给 to-spec，而不是 清空 它。

术语表是主要输出。该技能构建领域语言：项目自己的词，一次达成一致，这样你、智能体和你的同事就不必再次琢磨它们。并非所有人都认为这能提升智能体性能。最强烈的反对意见是：一个术语及其英文平实解释在 模型 中会得到相同结果，而术语表主要缩短的是共享它的人类之间的沟通。在这种观点下，术语表仍然有价值，但价值归属于人类。

常见问题¶

我该用这个还是 /wayfinder？ 范围决定选择。对于任何可以在一次会话中敲定的事情，使用这个；当工作量太大、无法在一次会话中承载时，使用 wayfinder，它会先把工作绘制成一张决策 工单 地图。Wayfinder 更慢、更密集，在范围明确的功能上使用它是常见错误。它不替代这个技能，并且可以为地图中适合的部分启动一次审问会话。

它运行了，但没有出现 GLOSSARY.md，也没有出现 ADR。 有两个已知原因。第一个是没有任何内容符合条件。ADR 需要全部三个关卡，而一次关于没有新词汇的变更的会话没有可写的内容。第二个是真实 bug。当该技能在另一个编排层内运行时（规范驱动开发包装器、多智能体框架、或将其作为他人流水线中一个步骤调用的规则），用户报告文件写入部分会静默不发生，而访谈仍然运行。该 bug 已提交且未修复。如果你处于这种设置中，在信任会话输出之前，先检查工作目录。

它一次性问了所有问题，没有给出建议，也从未提到 GLOSSARY.md。 这是该技能未能加载其两个依赖项。由于 SKILL.md 是一行委托，一个没有获取 grilling 和 domain-modeling 的智能体会猜测 grilling 的含义，于是你会一次性收到所有问题且没有结构。部分加载更令人困惑。grilling 加载了，domain-modeling 没有加载，你会得到一次好的访谈但没有书面记录。它发生的频率取决于模型和 effort 级别，并且是这个技能被报告最多的问题。如果你怀疑是这种情况，直接询问智能体它加载了哪些技能。

我的其他所有决策都去哪了？ 只进入了对话。这是关于该技能最严重的未解决抱怨。术语表不是规范，大多数答案不值得生成 ADR，也没有任何记录将每个已解决的答案关联到规范、工单和测试。后续步骤会将精确的答案（顺序保证、负面需求、数值默认值）弱化为更模糊的表述，结果可能看起来完整，却遗漏了你已经决定的内容。目前，请保留会话并直接将其交给 to-spec。然后，对照你自己的答案重新阅读规范，而不是假设它已经捕获了这些答案。

我可以把它指向一个完全没有文档的现有仓库吗？ 可以。对于没有 ADR、没有领域语言、没有设计原则的代码库，这是正确的技能：调用它并说“帮我记录我的仓库”。用户经常将它与 improve-codebase-architecture 搭配使用，用于构建或修复 GLOSSARY.md。请预期需要引导它。它会阅读代码，并就其发现的内容向你提问，由你决定代码库中已有的哪些词是正确的词。

会话结束时我该做什么？ 该技能的结束消息通常是开放式的，这是一个已知问题。在主流程中，答案是 to-spec，在同一对话中。如果变更足够小，可以立即构建，则直接改为 implement。

它为什么叫这个名字？ 没有人对这个名字满意。有一个未处理的建议将其重命名为 grill-domain-model，这能更准确地描述其行为。目前没有任何进展。如果重命名最终落地，文档页面会随之移动，URL 也会改变。

它正在正常工作的表现¶

• GLOSSARY.md 在会话期间逐条术语地变化，而不是在末尾一次性出现。
• 术语表读起来像纯词汇表（你项目的词语带有紧凑的定义），不包含实现细节或类似规范的表述。
• 代码库能够回答的问题会通过阅读代码库得到回答，而不是问你。
• 你得到很少或没有 ADR，而得到的那些是你不想再争论一遍的决策。
• 它会质疑你使用的某个词，因为你现有的术语表以不同方式定义了它。

它在哪里适用¶

grill-with-docs 是主构建链的起点：

grill-with-docs → to-spec → to-tickets → implement → code-review → retro

它发生在任何内容被写成规范之前。它产生共享的理解和确定的词汇，随后 to-spec 会将其综合起来，而不会再次访谈你。它的近邻是 grill-me，即没有仓库和文件的同一访谈，以及 domain-modeling，即它所驱动的术语表和 ADR 纪律；两者都使用 grilling 原语进行访谈。在它上游，wayfinder 规划过于庞大、无法在一次会话中完成的工作，并可以将地图的一部分交回给它。当你不确定哪个技能或流程适用时，ask-matt 会为你路由。