/grill-with-docs 技能

它能做什么

grill-with-docs 就计划或设计审问你，直到你和 agent 对它达成一致的理解，并在过程中把词汇和艰难决策写入你的仓库。它是同样的审问 grill-me runs (a round of questions, then wait, then the next round), pointed at a codebase.

它是 有状态。其他所有 追问审视 技能留下 会话 in your head; this one leaves files on disk. When a term resolves, the skill writes it to GLOSSARY.md at once, not in a batch at the end. When a decision passes three gates, the skill writes it as an ADR. That is the whole difference, and it also causes most of the trouble people have with the skill. The artifacts are real files in a real repo, so they can be missing when you expected them, and they can drift when more than one person writes them.

何时使用

你通过输入 /grill-with-docs, and the agent won't reach for it on its own.

当你准备在仓库中开始一项改动，而计划仍然模糊、相关概念的叫法也尚未统一时，就适合使用它。它面向单次会话。究竟该选择哪一种深度追问技能，取决于你当前面对的情况：

wayfinder 与它的分界可以归结为所需会话数：单次会话内能够完成的规划使用 /grill-with-docs；需要跨多次会话推进的规划使用 /wayfinder。

使用前提

技能写入你的仓库，所以你需要在一个安全写入的地方。已解决的术语进入 GLOSSARY.md glossary at the root, or to the relevant context's GLOSSARY.md，如果一个 GLOSSARY-MAP.md 位于根目录，把仓库标记为多上下文。决策进入 docs/adr/. The skill creates both only when it needs them. Nothing exists until the first term or decision is settled, so you set up nothing in advance.

它还需要另外两个技能在场，因为它自己的 SKILL.md is one line that delegates to them. 追问审视 supplies the interview, and domain-modeling 提供写作。安装 grill-with-docs 单独使用，得到的技能不工作。

落盘记录

一次会话会产生三类结果，但它们的去向和重要性并不相同。

第三行正是坑人的那一行。 GLOSSARY.md is only a glossary. It holds no implementation details, no spec, and no scratch notes. An ADR needs all three conditions at once, so most decisions do not qualify and most sessions produce none. A session that yields a sharper glossary and zero ADRs is working as designed, but it means most of what you agreed exists only in the 上下文窗口 你达成它的那个对话。把同一段对话交给 to-spec 而不是 清空上下文 它。

The glossary is the main output. This skill builds domain language: the project's own words, agreed once, so you, the agent and your colleagues do not have to work them out again. Not everyone agrees that this improves agent performance. The strongest objection is that a term and its plain-English expansion get the same result from the model, and that the vocabulary mainly shortens communication between the humans who share it. On that view the glossary is still valuable, but the value goes to the humans.

常见问题

我该用这个还是 /wayfinder? 范围决定它。一次会话能敲定的用这个； wayfinder 当任务大到一次装不下时，它把工作绘制成决策地图 tickets first. Wayfinder is slower and denser, and reaching for it on a well-scoped feature is the common mistake. It does not replace this skill, and it can start a grilling session for the parts of the map that suit one.

它运行了，但没有 GLOSSARY.md 而没有出现 ADR。 There are two known causes. The first is that nothing qualified. ADRs need all three gates, and a session about a change with no new vocabulary has nothing to write. The second is a real bug. When the skill runs inside another orchestration layer (a spec-driven-development wrapper, a multi-agent framework, a rule that invokes it as a step in someone else's pipeline), users report that the file-writing half silently does not happen, while the interview still runs. The bug is filed and unfixed. If you are in that setup, check the working directory before you trust the session's output.

它一次问完所有问题，没有推荐，也从未提到 GLOSSARY.md. 那是技能没能加载它的两个依赖。因为 SKILL.md 是一行委托，一个不接起 追问审视 and domain-modeling guesses at what grilling means, and you get every question at once with no structure. Partial loading is more confusing. grilling 加载， domain-modeling does not, and you get a good interview with no paper trail. How often it happens depends on the model and the 推理投入 层面，而且这是该技能被报告最多的问题。如果你怀疑它，直接问智能体加载了哪些技能。

我其他所有的决策去哪了？ Into the conversation only. This is the most serious open complaint about the skill. The glossary is not a spec, most answers do not earn an ADR, and no record links each resolved answer to a spec, a ticket and a test. Later steps soften precise answers (ordering guarantees, negative requirements, numeric defaults) into weaker prose, and the result can look complete while missing the thing you decided. For now, keep the session and feed it straight to to-spec. Then re-read the spec against your own answers rather than assuming it captured them.

我能让它指向一个完全没有文档的现有仓库吗？ Yes. This is the right skill for a codebase with no ADRs, no domain language and no design principles: invoke it and say "help me document my repo". Users often pair it with improve-codebase-architecture 用于构建或修复 GLOSSARY.md. Expect to steer it. It reads code and asks you about what it finds, and you decide which of the words already in the codebase are the right ones.

会话结束时我该做什么？ The skill's closing message is often open-ended, which is a known problem. In the main flow the answer is to-spec，在同一个对话中。如果改动小到可以立即构建，直接去 implement 代替。

为什么它叫那个名字？ 没人喜欢这个名字。有一个开放的改名建议 grill-domain-model, which describes the behaviour more accurately. Nothing has moved on it. If a rename ever lands, the docs page moves with it and the URL changes.

出现这些迹象，说明它工作正常

• GLOSSARY.md changes during 会话中，逐个术语，而不是最后一次性出现。
• The glossary reads as pure vocabulary (your project's words with tight definitions) and contains no implementation detail or spec-like prose.
• 代码库本身能够回答的问题，会通过阅读代码得到答案，而不会再抛给你。
• You get few or no ADRs, and the ones you get are decisions you would be annoyed to have to argue again.
• 当你使用的词与现有词汇表定义不一致时，它会主动指出并要求你澄清。

它在流程中的位置

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

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

It comes before anything is written down as a spec. It produces the shared understanding and settled vocabulary that to-spec 然后无需再次审问你就能综合。它的近邻是 grill-me，同样的审问，但没有仓库、没有文件，而且 domain-modeling, the glossary-and-ADR discipline it drives; both use the 追问审视 primitive for the interview. Upstream of it, wayfinder 绘制一次会话装不下的大型任务图，并能把地图的部分交还给它。当你不确定哪个技能或流程合适时， ask-matt 为你指路。