grillkit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

grillkit

Interview the user relentlessly about their idea until the two of you reach a genuinely shared understanding. The subject can be anything: a rough concept, a design in their head, an existing plan file, an architecture, a PR. You don't need a formal plan to grill. Map it as a design tree, where every decision branches into the decisions that hang off it. Do not start building; the point is to surface every unresolved decision first.

持续追问用户的想法，直到双方达成真正的共识。质询对象可以是任何内容：粗略概念、脑海中的设计、现有计划文件、架构、PR。进行质询无需正式计划。将其映射为design tree（设计树），每个决策都会延伸出依赖它的其他决策。不要急于开始构建；核心是先梳理出所有未解决的决策。

How to grill

如何进行质询（grill）

Open by reflecting the idea back. Before the first question, restate the subject in your own words: the goal you understand, the shape you're about to grill. This surfaces a misread up front, so you and the user are grilling the same idea rather than diverging silently for ten questions.
Work the tree in rounds. The frontier is every decision whose prerequisites are already settled, meaning the questions you can ask now without guessing at answers you haven't heard yet. Ask the whole frontier in one round, numbered, then wait for the user's answers before the next round. A question whose answer depends on another question still open in this round belongs to a later round, not this one. Asking the round is the format.
Each round reshapes the tree. The answers settle decisions, which pushes the frontier outward and unblocks the questions that depended on them. Recompute the frontier and ask the next round.
Always recommend an answer. For every question, state the option you'd pick and why. A naked question offloads the thinking; a recommendation gives the user something concrete to accept, reject, or refine.
Probe the soft spots. Push hardest on unstated assumptions, hand-waved edge cases, error and failure paths, scope boundaries, and anything described vaguely. If an answer is thin, follow up in the next round rather than letting it stand.

先反馈想法。提出第一个问题前，用自己的话重述质询主题：你理解的目标、即将质询的框架。这能提前发现误解，避免双方在质询过程中悄然偏离同一方向。
按轮次梳理设计树。**frontier（前沿决策）**指所有前置条件已明确的决策，即你当前无需猜测未知答案就能提出的问题。将整轮前沿决策编号列出，等待用户回复后再进行下一轮。若某个问题的答案依赖本轮中尚未解决的其他问题，则该问题属于后续轮次，而非当前轮次。询问轮次有固定格式。
每轮都会重构设计树。用户的答案会敲定部分决策，从而拓展前沿决策范围，解锁依赖这些决策的问题。重新梳理前沿决策，然后开启下一轮质询。
始终提供推荐答案。每个问题都要说明你会选择的选项及理由。单纯提问会将思考负担转嫁给用户；提供推荐答案能让用户有具体的内容可接受、拒绝或细化。
探查薄弱点。重点追问未阐明的假设、含糊带过的边缘情况、错误与故障路径、范围边界，以及任何描述模糊的内容。若答案不够充分，在下一轮继续跟进，而非就此放过。

Asking the round

询问轮次

A grill is only as good as the user's ability to answer it fast. Dense paragraphs with choices buried mid-sentence make a good question unanswerable, because the reader has to parse prose to find the decision. Every rule below exists to keep a round scannable in one pass.

质询的有效性取决于用户快速作答的能力。密集段落中隐藏在句子中间的选项会让问题难以回答，因为读者需要解析冗长文字才能找到决策点。以下所有规则都是为了让每轮质询能被快速浏览。

The shape of a round

轮次格式

undefined

undefined

Round 2: 3 open decisions

Blocked behind this round: storage format, migration path.

❓ Q4. Where does the doc map live? Stakes:

update

needs a code-path → page lookup without reading every page, and

audit

's recency prefilter needs to know which paths a page describes.

(a) Per-page colocated metadata. Can't drift from the page, one grep pass, invisible in every renderer
(b) YAML frontmatter. GitHub renders it as a visible table, and it may collide with an engine's own schema
(c) Central manifest. One more file to keep in sync
(d) Re-derive each run. No drift, but throws away the cheapness
```
audit
```
depends on

➡️ (a) as an HTML comment under the visible stamp:

<!-- wikikit: documents: src/cli/**, package.json -->

❓ Q5. Contributor docs: in or out? Stakes: dev-env setup and release steps are derivable from the repo; a CONTRIBUTING.md is a social contract that isn't in the repo at all.

(a) Split on that seam. Mechanical half becomes how-tos, the social half stays out
(b) All in. Pulls PR etiquette and CoC into scope, which can only be invented
(c) All out. Loses two how-tos that verify cleanly

➡️ (a) with

how-to/set-up-a-dev-environment.md

and

how-to/cut-a-release.md

joining the doc set; root

CONTRIBUTING.md

is never written, only linked.

⏳ Q6. Which renderer serves these pages? Waiting on a sub-agent checking the repo for a docs generator. It gates the frontmatter decision, so it lands next round.

4a 5b

, or "go with your picks" to take both.

undefined

Blocked behind this round: storage format, migration path.

❓ Q4. Where does the doc map live? Stakes:

update

needs a code-path → page lookup without reading every page, and

audit

's recency prefilter needs to know which paths a page describes.

(a) Per-page colocated metadata. Can't drift from the page, one grep pass, invisible in every renderer
(b) YAML frontmatter. GitHub renders it as a visible table, and it may collide with an engine's own schema
(c) Central manifest. One more file to keep in sync
(d) Re-derive each run. No drift, but throws away the cheapness
```
audit
```
depends on

➡️ (a) as an HTML comment under the visible stamp:

<!-- wikikit: documents: src/cli/**, package.json -->

❓ Q5. Contributor docs: in or out? Stakes: dev-env setup and release steps are derivable from the repo; a CONTRIBUTING.md is a social contract that isn't in the repo at all.

(a) Split on that seam. Mechanical half becomes how-tos, the social half stays out
(b) All in. Pulls PR etiquette and CoC into scope, which can only be invented
(c) All out. Loses two how-tos that verify cleanly

➡️ (a) with

how-to/set-up-a-dev-environment.md

and

how-to/cut-a-release.md

joining the doc set; root

CONTRIBUTING.md

is never written, only linked.

⏳ Q6. Which renderer serves these pages? Waiting on a sub-agent checking the repo for a docs generator. It gates the frontmatter decision, so it lands next round.

4a 5b

, or "go with your picks" to take both.

undefined

The rules that produce it

格式规则

Options are a list, never prose. One option per line, always, even for a binary.
```
Options: (a) …, (b) …, (c) …
```
inside a sentence is the single worst readability offender in a grill. Forcing a two-way choice into list shape is also what surfaces a seam you'd otherwise bury in sentence four.
Each option carries its own trade-off. Put the reason to reject (b) on (b)'s line. A recommendation that argues against three options the reader last saw 200 characters ago makes them ping-pong up and down the round.
Stakes first, two sentences max. Label it
```
Stakes:
```
and say why the decision is load-bearing, meaning what breaks or stays undecided downstream. Everything else belongs on the option lines.
The recommendation is one line.
```
➡️ **(a)** <the concrete form it takes>
```
. Point at the letter, then add only what the list couldn't carry: the exact syntax, path, or shape you'd write. Never restate the option's own description.
Rule off between questions. A
```
---
```
renders as a horizontal line in every terminal and stops questions bleeding into each other.
Number continuously across rounds. Q1–Q3 in round one, Q4 onward in round two. Restarting at Q1 each round makes "Q2" ambiguous the moment anyone refers back, including your own recap in Hand off.
Code spans are for literals only. Paths, filenames, flags, commands, identifiers. Use italics for conceptual emphasis. Code-spanning ordinary prose words turns the round into rainbow noise and hides the spans that are real references.
Show what's pending, don't hide it. When a sub-agent is still fetching a fact a question depends on, list that question with
```
⏳
```
and name what it's waiting for. A visible branch that goes unasked reads as forgotten; one line explains it's blocked, not dropped.
Head the round and close it. The header gives a progress signal, meaning how many decisions are open now and what they unblock, which is otherwise unknowable and makes a long grill feel endless. The closing line names the reply format so the user doesn't invent one every round.

选项用列表呈现，而非段落文字。每个选项单独一行，即使是二选一的问题也是如此。句子中嵌入
```
Options: (a) …, (b) …, (c) …
```
是最影响可读性的做法。将双向选择转化为列表格式，还能暴露原本会隐藏在句子中的逻辑缝隙。
每个选项都标注自身的权衡点。将拒绝选项(b)的理由放在选项(b)的行中。若推荐答案需要反驳用户200字符前看到的三个选项，会让用户反复上下翻阅轮次内容。
先说明影响，最多两句话。标注为
```
Stakes:
```
，说明该决策为何至关重要，即下游会有哪些内容受影响或无法确定。其他信息都放在选项行中。
推荐答案单独一行。
```
➡️ **(a)** <具体形式>
```
。指向选项字母，补充列表无法体现的内容：确切的语法、路径或格式。不要重复选项本身的描述。
用分隔线区分问题。
```
---
```
在所有终端中都会显示为水平线，避免问题之间相互混淆。
跨轮次连续编号。第一轮为Q1–Q3，第二轮从Q4开始。若每轮都从Q1重新编号，会导致“Q2”产生歧义，包括你在交接部分的回顾内容。
代码跨度仅用于字面量。路径、文件名、标志、命令、标识符。用斜体进行概念强调。将普通散文词汇用代码跨度标记会让轮次内容杂乱无章，掩盖真正的引用内容。
展示待处理内容，而非隐藏。当子代理仍在获取某个问题依赖的事实时，用
```
⏳
```
标记该问题，并说明等待的内容。未提出的可见分支会让人误以为被遗忘；用一行文字说明它处于阻塞状态，而非被丢弃。
为轮次添加标题和结尾。标题提供进度信号，说明当前有多少未解决的决策以及它们会解锁哪些内容，否则用户无法知晓进度，导致冗长的质询过程显得遥遥无期。结尾说明回复格式，避免用户每轮都自行创造格式。

Offer the picker when you have one

若有选择器则提供

With

AskUserQuestion

available, run the round hybrid: print the full text round first, with stakes, trade-offs, evidence, and recommendation, then call the tool for the picks alone. The user clicks instead of retyping letters, and the reasoning still gets read.

The picker mirrors the text round exactly. Same questions in the same order, same options in the same order inside each question. The widget is a second view of the round the user just read, not a fresh presentation of it. Reorder either one and the letters stop meaning anything: the user reads the case for
```
(c)
```
, then clicks the third option and gets something else.
Write the recommended option as
(a)
whenever the list has no order of its own. The user takes the recommendation most of the time, so landing it in the first slot means a single click with no arrow keys, and because the picker mirrors the text round, ordering it once at the top gets it right in both views. Keep the merits order instead when the options carry one (a spectrum, escalating scope, a chronology), since scrambling that to save a keystroke costs the reader more than it saves.
Do the ordering while writing the options, never between the two views. Reordering at picker time is what breaks the letters, and it's unnecessary:
```
(Recommended)
```
marks the pick wherever it sits.
Prefix every label with its letter, as in
```
(a) Per-page metadata
```
,
```
(b) YAML frontmatter
```
. That makes the correspondence explicit rather than positional, so a
```
(b)
```
still reads as
```
(b)
```
even when the widget stamps its own numbering down the side.
Mark the recommended option
```
(Recommended)
```
at the end of its label, wherever in the order it happens to fall, so the picker agrees with the
```
➡️
```
line.
Keep the labels short; the rationale lives in the text round, not in the option descriptions.
The tool caps at 4 questions per call and 4 options per question, and it always appends an "Other" escape for the user's own answer. A wider frontier means batching calls in round order or falling back to the text round alone; never trim the frontier to fit the widget. A question with a fifth option can't be mirrored at all: either fold two options together in both views, or leave that one question to the text round rather than showing the picker a truncated list.

当

AskUserQuestion

可用时，采用混合模式运行轮次：先打印完整的文字轮次内容，包括影响、权衡点、依据和推荐答案，再调用工具单独获取选择结果。用户只需点击而非重新输入字母，同时仍能阅读推理过程。

选择器与文字轮次完全一致。问题顺序相同，每个问题内的选项顺序也相同。选择器是用户刚阅读的轮次的另一种呈现形式，而非全新展示。若任意一方调整顺序，字母将失去意义：用户阅读了选项(c)的理由，点击第三个选项却得到其他内容。
当列表无固有顺序时，将推荐选项设为
(a)
。用户大多会接受推荐答案，因此将其放在第一个位置只需点击一次，无需使用方向键；由于选择器与文字轮次一致，在顶部排序一次就能让两者都正确。若选项有固有顺序（如范围递增、时间顺序），则保留该顺序，因为为了节省一次按键而打乱顺序对读者造成的损失更大。
在编写选项时完成排序，而非在两种视图之间调整。在选择器阶段重新排序会导致字母对应错误，而且毫无必要：
```
(Recommended)
```
标记会显示推荐选项的位置。
每个标签前都加上字母前缀，例如
```
(a) Per-page metadata
```
、
```
(b) YAML frontmatter
```
。这能明确对应关系，而非仅依赖位置，即使小部件在侧边添加了自己的编号，
```
(b)
```
仍会被识别为
```
(b)
```
。
在推荐选项的标签末尾标记
```
(Recommended)
```
，无论它在顺序中的哪个位置，确保选择器与
```
➡️
```
行一致。
标签要简短；理据放在文字轮次中，而非选项描述里。
该工具每次调用最多支持4个问题，每个问题最多4个选项，并且始终会追加一个“其他”选项供用户自定义答案。若前沿决策较多，需按轮次分批调用，或退化为纯文字轮次；绝不要为了适配小部件而删减前沿决策。若某个问题有第五个选项，则无法同步到选择器：要么在两种视图中合并两个选项，要么将该问题留在文字轮次中，而非向选择器展示截断后的列表。

Facts are your job, decisions are theirs

事实由你负责，决策由用户负责

Finding facts is never the user's job. If something is discoverable by reading the codebase, docs, or config, find it yourself instead of asking, and reserve your questions for genuine decisions, the judgment calls that are the user's to make.

When a frontier question needs a fact from the environment (filesystem, tools, config) and you have a sub-agent tool, dispatch a sub-agent to find it, and don't block on it. A running exploration is just an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now and list the blocked one with

⏳

so the user can see it's pending rather than missing. With no sub-agent tool available, look the fact up inline before you put the dependent question to the user.

查找事实永远不是用户的工作。若某内容可通过阅读代码库、文档或配置找到，应自行查找，仅将问题留给真正的决策——即由用户做出的判断性选择。

当前沿决策需要环境中的事实（文件系统、工具、配置）且你有子代理工具时，派遣子代理去查找，不要等待结果。正在进行的探索只是未明确的前置条件，因此只有依赖该事实的下游问题需要等待子代理报告；现在就询问其余前沿决策，并用

⏳

标记阻塞的问题，让用户看到它处于待处理状态而非被遗漏。若无子代理工具，在向用户提出依赖该事实的问题前，先自行查找相关事实。

When to stop

何时停止

The grill is done when the frontier is empty, every branch of the design tree visited, nothing left silently assumed. Then hand off, and do not begin implementing until the user explicitly says to proceed.

当前沿决策为空，设计树的每个分支都已梳理完毕，没有任何未阐明的假设时，质询即完成。然后进行交接，在用户明确指示前不要开始实施。

What to do with the result

处理结果

grillkit's job is the shared understanding, not a particular file, but where that understanding lands depends on how the session started:

Started from a plan file. When the input was an existing plan document (e.g. a
```
plan-<slug>-YYYY-MM-DD.md
```
), fold the settled decisions back into that same file by default, without asking. The user handed you a plan to harden; returning it hardened is the expected outcome. Rewrite that same file in place, without spawning a parallel copy or changing its creation-date suffix, and tell the user you updated it. Only skip or redirect the write if the user explicitly asked for something else (a standalone note, no file, a different location). Stamp the hardened plan with a
```
Grilled: YYYY-MM-DD
```
line directly under the title (today's date; update it on a re-grill). The stamp is a durable, machine-readable signal that this plan has survived a grill, and downstream tooling reads it as provenance: issuekit, for one, only labels a plan's issues
```
ready
```
(safe for unattended work) when the source carries this stamp, and files ungrilled plans as
```
needs-planning
```
instead. It is provenance rather than a tracker artifact, so it is written the same way on a project that files no issues at all. No filesystem? Print the stamp line with the recap for the user to add themselves.
Started from anything else. With a rough idea, a design in someone's head, an architecture, or a PR, there's no file to return to, so ask where the decisions should go: update some existing file in place, write a standalone note in the current directory, or nothing at all. Don't write a file unprompted and don't assume a location; grillkit doesn't own a canonical plan-doc format or a
```
docs/plans
```
convention.

If grilling settled a domain term or a hard-to-reverse trade-off decision worth keeping, domainkit is the scribe when installed; otherwise note the settled decision for the user to record as a glossary entry or ADR. grillkit does the interrogating rather than owning that format.

grillkit的职责是达成共识，而非生成特定文件，但共识的落地方式取决于会话的起始状态：

从计划文件开始。若输入是现有计划文档（如
```
plan-<slug>-YYYY-MM-DD.md
```
），默认将敲定的决策合并回原文件，无需询问。用户交给你一份计划来强化；返回强化后的计划是预期结果。原地重写该文件，不要生成副本或修改其创建日期后缀，并告知用户已更新。仅当用户明确要求其他结果（如独立笔记、不生成文件、其他位置）时，才跳过或重定向写入操作。为强化后的计划添加标记，在标题正下方添加
```
Grilled: YYYY-MM-DD
```
行（当天日期；再次质询时更新该日期）。该标记是一个持久的、机器可读的信号，表明此计划已通过质询，下游工具会将其视为来源凭证：例如issuekit仅当源文件带有此标记时，才会将计划对应的问题标记为
```
ready
```
（可独立处理），否则会将未质询的计划标记为
```
needs-planning
```
。它是来源凭证而非跟踪工件，因此即使在不提交问题的项目中，也会以相同方式写入。若无文件系统？则打印标记行和回顾内容，供用户自行添加。
从其他内容开始。若起始内容是粗略想法、脑海中的设计、架构或PR，则没有可返回的文件，因此询问决策应落地何处：原地更新现有文件、在当前目录写入独立笔记，或不生成任何文件。不要未经提示就写入文件，也不要假设位置；grillkit不拥有标准的计划文档格式或
```
docs/plans
```
约定。

若质询敲定了值得保留的领域术语或难以逆转的权衡决策，且已安装domainkit，则由domainkit负责记录；否则将敲定的决策告知用户，供其记录为术语表条目或ADR（架构决策记录）。grillkit仅负责质询，不负责该格式的维护。

Hand off

交接

Write this section in the procedural register: one instruction per sentence, active voice, present tense, no metaphor.

Close every grill the same way, naming a sibling skill only when it's installed and otherwise describing the action plainly:

What changed. Give a brief recap of the decisions you settled together, each in a line. Name any question you raised and didn't resolve; a decision the user deferred is not a decision, and it will surface again downstream as a blocked build.

Where it landed. Name the plan file you rewrote in place and its

Grilled:

stamp, or the file you were asked to write instead, or nothing at all when the user declined a file.

Next. The stamp is the whole point of finishing a grill, so say what it unlocks. Where the project tracks work in GitHub Issues, a hardened plan is ready to become issues, and issuekit reads the stamp to file them as

ready

(safe to work unattended) rather than

needs-planning

. Where it tracks work elsewhere or nowhere, the same stamp clears the plan to be built, so name implementkit and its first phase instead. Do not assume the first case: a project on GitHub may still run its backlog in Linear, Jira, or a file, and the prompt or the repo's agent-guide file is what says which. Without a plan file, name what the decisions feed instead, either the build itself (implementkit) or a decision record (domainkit). Don't start either; grilling ends at the shared understanding.

本节采用流程化表述：每句一个指令，主动语态，现在时，无隐喻。

每次质询都以相同方式收尾，仅当相关技能已安装时才提及同类工具，否则直接描述操作：

变更内容。简要回顾双方敲定的所有决策，每项决策单独一行。列出你提出但未解决的问题；用户推迟的决策不算已敲定，它会在下游流程中以构建阻塞的形式再次出现。

落地位置。说明你原地重写的计划文件及其

Grilled:

标记，或你按要求写入的其他文件，或用户拒绝生成文件时说明未生成任何文件。

下一步。完成质询的核心价值在于该标记，因此说明它解锁了哪些操作。若项目在GitHub Issues中跟踪工作，强化后的计划可转化为问题，issuekit会读取标记并将问题标记为

ready

（可独立处理），而非

needs-planning

。若项目在其他地方或未跟踪工作，该标记同样表明计划可进入构建阶段，因此提及implementkit及其第一阶段。不要假设是第一种情况：GitHub上的项目可能仍在Linear、Jira或文件中管理待办事项，提示或仓库的agent-guide文件会说明具体方式。若无计划文件，说明决策会输入到哪里：要么是构建本身（implementkit），要么是决策记录（domainkit）。不要启动任何操作；质询在达成共识时结束。