grillkit

grillkit

あなたのアイデアについて、二人が本当に共通の理解に達するまで、徹底的に質問します。対象は何でもかまいません。大まかなコンセプト、頭の中にあるデザイン、既存の計画ファイル、アーキテクチャ、PRなどです。質問を始めるのに正式な計画は必要ありません。すべての決定が、それに関連する決定へと枝分かれするデザインツリーとして整理します。作り始めないでください。目的は、未解決の決定をすべて先に洗い出すことです。

質問の進め方

• まず、アイデアを自分の言葉で言い換えます。 最初の質問の前に、理解している目標と、これから質問する内容の概要を言い直します。これにより、最初に誤解を明らかにし、十問もすれ違ったまま質問を続けるのではなく、ユーザーと同じアイデアをもとに質問できます。
• ラウンドごとにツリーを進めます。 フロンティアとは、前提となる決定がすでに確定しているすべての決定を指します。つまり、まだ聞いていない回答を推測せずに、今質問できる内容です。フロンティア全体を番号付きで一度に質問し、ユーザーの回答を待ってから次のラウンドに進みます。回答が、このラウンドでまだ未解決の別の質問に依存する場合、その質問はこのラウンドではなく、後のラウンドに回します。ラウンドの質問の形式に従ってください。
• 各ラウンドでツリーを組み替えます。 回答によって決定が確定し、フロンティアが広がり、それまで回答待ちだった質問が可能になります。フロンティアを再計算して、次のラウンドの質問をします。
• すべての質問に推奨案を添えます。 各質問で、自分ならどの選択肢を選ぶか、またその理由を伝えます。質問だけでは考える作業をユーザーに押しつけてしまいますが、推奨案があれば、ユーザーは具体案を受け入れたり、断ったり、調整したりできます。
• ユーザーの判断が必要なことだけを尋ね、残りはデフォルトにします。 ほとんどの推奨案はそのまま受け入れられるため、ラウンドではユーザーの判断が必要な決定だけを質問し、それ以外はすべて番号を指定して変更できるデフォルトとして列挙します。質問するか、デフォルトにするかの基準に従ってください。
• 曖昧な点を掘り下げます。 明示されていない前提、曖昧に処理されたエッジケース、エラーや失敗時の処理、スコープの境界、漠然とした説明について、とくに重点的に確認します。回答が不十分なら、そのままにせず、次のラウンドで追加質問します。各決定への追加質問は一度までです。二度目の回答も不十分な場合は、保留として記録し、フロンティアから外します。
• 未解決のことだけを質問します。 各ラウンドには、未解決の決定だけを含めます。確定した決定がフロンティアに戻るのは、後の回答と矛盾した場合だけです。その際は、どの回答によって再び未解決になったのかをラウンド内で示します。

ラウンドの質問

質問にすばやく答えられるかどうかで、質問の質が決まります。選択肢が文の途中に埋め込まれた長い段落では、決定内容を見つけるために文章を読み解く必要があり、良い質問でも答えにくくなります。以下のルールはすべて、ラウンド全体を一目で確認できるようにするためのものです。

質問するか、デフォルトにするか

ラウンドを書く前に、フロンティア上のすべての判断を分類します。この分類で決まるのはラウンド内での扱いであり、推奨するかどうかではありません。どちらの場合も推奨案を提示します。

次のいずれかに当てはまる判断は、質問します。

• ドメインまたはプロダクト。 プロダクトの機能や対象者、ビジネスルール、価格設定、ドメイン用語の名称や意味、スコープに含めるもの・含めないもの。
• 好み。 ビジュアルデザイン、コピー、トーン、ユーザーに見える名称。
• 元に戻しにくい。 データモデル、公開 API や CLI の仕様、マイグレーション、外部との契約、コストの確約、セキュリティやプライバシーに関するトレードオフ。
• 推奨の根拠が弱い。 選択肢の差が小さい、根拠が薄い、または自分の選択がユーザーの発言に反する。
• 外部へのアクション。 プラン自体のブランチを越えるあらゆる操作の許可。停止のタイミングにあるビルド停止ラウンドでは、必ずこれらを質問します。

それ以外はすべてデフォルトにします。つまり、異論なく有能な実装者が選ぶ仕組み、後のコミットで簡単に覆せる選択、リポジトリの規約ですでに決まっている選択です。分類に迷ったら、質問します。

ユーザーがラウンドに返信し、デフォルトを上書きしなかった時点で、そのデフォルトは確定します。上書きされた場合は、ユーザーの回答によって判断が確定し、質問した判断と同じ追加質問および保留のルールが適用されます。後の回答と矛盾しない限り、デフォルトが後のラウンドに再登場することはありません。

この分類はエージェントが行うため、ユーザーにも見える必要があります。すべてのデフォルトを、理由を一行添えてラウンドの表に記載します。また、引き継ぎの要約では、確定した各判断が質問によるものか、デフォルトによるものかを示します。

すべてのフロンティア上の判断が、デフォルトの表に記載されるか、質問として書かれた時点で、この分類は完了です。

ラウンドの形式

### Round 2: 5 open decisions, 2 asked, 2 defaulted
Blocked behind this round: storage format, migration path.

**Defaults.** Taken unless you change one by number.

| # | Decision | Default | Why |
|---|---|---|---|
| Q4 | Page file names | (a) kebab-case from the page title | matches the repo's existing docs |
| Q5 | Link style between pages | (a) relative Markdown links | renders in GitHub and in every engine |

---

❓ **Q6. 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: ``

---

❓ **Q7. 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.

---

⏳ **Q8. 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.

Reply `6a 7b`, change a default with its number (`5b`), or say "go with your picks" to take everything.

これを生み出すルール

• 選択肢は文章ではなくリストにします。 常に1行に1つずつ記載します。二択の場合も同じです。文章の中に Options: (a) …, (b) …, (c) … と入れるのは、質問攻めで最も読みづらくなる要因です。二択をリスト形式にすることで、4文目に埋もれてしまう継ぎ目も表面化します。
• 各選択肢には、それぞれのトレードオフを添えます。 (b)を選ばない理由は、(b)の行に記載します。読者が200文字前に見た選択肢3つに対して、後から推奨案で反論すると、ラウンド内を行ったり来たりさせてしまいます。
• 最初に重要性を示し、最大2文にします。 Stakes: とラベルを付け、なぜその決定が後続に影響するのか、つまり何が壊れるのか、何が未決定のままになるのかを説明します。それ以外はすべて選択肢の行に記載します。
• 推奨案は1行にまとめます。 ➡️ **(a)** <the concrete form it takes>。選択肢の記号を示し、リストだけでは伝えられない内容、つまり実際に記述する正確な構文、パス、または形式だけを付け加えます。選択肢の説明を繰り返してはいけません。
• 質問ごとに区切ります。 --- はすべてのターミナルで水平線として表示され、質問同士が混ざるのを防ぎます。
• ラウンドをまたいで番号を連続させます。 1ラウンド目はQ1～Q3、2ラウンド目はQ4から始めます。各ラウンドでQ1から振り直すと、誰かが以前の質問に言及した瞬間に「Q2」が曖昧になります。引き継ぎで自分の要約に言及するときも同じです。
• コードスパンはリテラルにだけ使います。 パス、ファイル名、フラグ、コマンド、識別子に使います。概念を強調するには斜体を使います。通常の文章をコードスパンにすると、ラウンドが虹色のノイズのようになり、実際の参照を示すコードスパンが埋もれてしまいます。
• 保留中の内容は隠さず、明示します。 質問に必要な事実をサブエージェントがまだ取得中の場合は、その質問を ⏳ とともに記載し、何を待っているのかを示します。尋ねられないまま残った分岐は忘れられたように見えますが、1行添えれば、抜け落ちたのではなく保留中だと伝わります。
• デフォルトを先に、1つの表にまとめます。 デフォルトごとに1行を使い、番号、決定事項、記号付きの選択肢、1つのセルに収まる短い理由を記載します。デフォルトには重要性の説明も選択肢リストも必要ありません。デフォルトを変更したいユーザーが、選択肢を尋ねればよいのです。デフォルトがないラウンドでは表を省きます。
• ラウンドには見出しを付け、最後に締めくくります。 見出しでは進捗を示します。現在未決定の事項、質問済みの事項、デフォルトで決まった事項がそれぞれいくつあるか、さらにそれらの決定によって何が可能になるかを示します。これらが分からないと、長い質問攻めがいつまでも終わらないように感じられます。最後の行では返信形式を指定し、ユーザーがラウンドごとに形式を考えずに済むようにします。

ピッカーが使える場合は、ピッカーを提示します

AskUserQuestion が使える場合は、ラウンドをハイブリッド形式で進めます。まず、重要度、トレードオフ、根拠、推奨案を含む全文を提示し、その後、選択肢だけをツールに渡します。ユーザーは文字を打ち直す代わりにクリックでき、判断の根拠も読めます。

• ピッカーに含めるのは、質問された内容だけです。 デフォルト値は表に残します。ユーザーが変更する場合は、返信に数字を1つ加えるだけです。
• ピッカーはテキスト形式のラウンドを正確に反映します。 質問の順序も、各質問内の選択肢の順序も同じにします。ウィジェットは、ユーザーが読んだラウンドを別の形で表示するものであり、新たに提示し直すものではありません。どちらかの順序を変えると、文字の意味がなくなります。ユーザーが (c) の根拠を読んだ後に3番目の選択肢をクリックしても、別の内容が選ばれてしまうからです。
• 選択肢に固有の順序がない場合は、推奨案を (a) にします。 ユーザーはたいてい推奨案を選ぶため、最初に置けば矢印キーを使わずにクリックできます。また、ピッカーはテキスト形式のラウンドを反映するので、最初に一度だけ先頭に置けば、どちらの表示でも正しくなります。選択肢自体に順序がある場合（スペクトラム、段階的な範囲、時系列など）は、その順序を優先してください。キー入力を1回省くために順序を崩すと、読者の負担がそれ以上に増します。
• 選択肢を作成する段階で順序を決め、2つの表示の間で並べ替えないでください。 ピッカーを作るときに並べ替えると文字との対応が崩れますが、その必要はありません。(Recommended) を付ければ、どこにあっても推奨案だと分かります。
• すべてのラベルの先頭に文字を付けます。 例：(a) ページ単位のメタデータ、(b) YAML frontmatter。これにより、位置ではなく明示的な対応関係になります。ウィジェットが横に独自の番号を付けても、(b) は常に (b) として読めます。
• 推奨案には、順序に関係なく、ラベルの末尾に (Recommended) を付けます。これにより、ピッカーと ➡️ の行が一致します。
• ラベルは短くします。根拠はテキスト形式のラウンドに記載し、選択肢の説明には含めません。
• ツールは1回の呼び出しにつき質問を最大4件、各質問の選択肢を最大4つまで受け付け、ユーザーが独自の回答を入力できる「Other」を必ず追加します。選択肢の範囲が広い場合は、ラウンドの順序に沿って複数回に分けて呼び出すか、テキスト形式のラウンドだけを使います。ウィジェットに収めるために選択肢を削ってはいけません。5つ目の選択肢がある質問は、ピッカーでは完全に反映できません。両方の表示で2つの選択肢をまとめるか、その質問だけはテキスト形式のラウンドに残し、選択肢を省略したピッカーを提示しないでください。

事実を調べるのはあなたの役目、決めるのはユーザーの役目です

事実を調べるのは、決してユーザーの役目ではありません。コードベース、ドキュメント、設定を調べれば分かることは、質問せずに自分で確認し、本当にユーザーが判断すべき決定事項、つまりユーザー自身が決めるべき判断だけを質問してください。

ラウンドの質問に環境（ファイルシステム、ツール、設定）から得られる事実が必要で、サブエージェントツールが使える場合は、サブエージェントに調査を依頼し、結果を待たずに進めます。 調査中の項目は未確定の前提条件にすぎないため、待つのはその項目に依存する質問だけです。残りの質問は今すぐ提示し、保留中の質問には ⏳ を付けて、抜けているのではなく確認待ちだとユーザーに分かるようにします。サブエージェントツールが使えない場合は、依存する質問をユーザーに提示する前に、自分でその事実を確認してください。

停止するタイミング

フロンティアが空だと判断する前に、対象がビルドされるものである場合は、ビルド停止ラウンドで確認してください。 ここに挙げるのは、ビルドを止めて確認する必要があるものの、回答する人がいない場合に最も大きなコストが発生する質問です。

• 外部へのアクション。 フォローアップのイシュー作成、プッシュ、デプロイなど、計画で自身のブランチを越えて実行する各アクションの許可。
• テストインフラストラクチャ。 リポジトリにまだ存在しない種類のテストを求める各フェーズについて、実行環境と方法。
• 立ち会いが必要なフェーズ。 デザインの選定やモックアップの承認など、人が必要な各フェーズ。グリルで対応できるなら、今ここで決めてください。そうでなければ、立ち会いが必要なままであることと、無人で実行できるフェーズより前に行われることを確認してください。

計画ですでに回答済みの質問は省略してください。

フロンティアが空になった時点で、グリルは完了です。設計ツリー内のすべての決定が確定しているか、保留として明示されています。ユーザーはどのラウンドでもグリルを止めることができ、その時点で未決の決定は保留になります。その後、引き継ぎを行い、ユーザーが明示的に進めるよう指示するまで実装を開始しないでください。

結果の扱い方

grillkitの役割は、特定のファイルではなく、共通認識を形にすることです。ただし、その共通認識をどこに反映するかは、セッションの開始方法によって異なります。

• プランファイルから開始した場合。 入力が既存のプラン文書（例：NNNN-plan-<slug>-YYYY-MM-DD.md、または通し番号のない古い形式）だった場合は、特に確認せず、確定した決定事項を既定で同じファイルに反映してください。ユーザーはプランをより確かなものにするために渡しています。それを確かなものにして返すのが期待される結果です。別のファイルを作ったり、名前や通し番号、作成日を含むサフィックスを変更したりせず、同じファイルをその場で書き換え、更新したことをユーザーに伝えてください。ユーザーが明示的に別のもの（独立したメモ、ファイルなし、別の場所など）を求めた場合に限り、書き込みを省略または変更してください。確かなものにしたプランには、タイトルの直下に Grilled: YYYY-MM-DD の行を記入してください（今日の日付を使い、再度グリルする場合は更新します）。このスタンプは、プランがグリルを経たことを示す、永続的で機械可読なシグナルです。下流のツールはこれを来歴情報として読み取ります。たとえばissuekitは、ソースにこのスタンプがある場合に限り、プランの課題を ready（無人作業に安全）とラベル付けし、グリルされていないプランは needs-planning として扱います。これはトラッカー上の成果物ではなく来歴情報なので、課題を一切登録しないプロジェクトでも同じように記入します。このスタンプが示すのは、グリル時点のプランです。それ以降の編集は対象外です。 確定済みの設計判断の追加、削除、変更、フェーズの追加、削除、スコープ変更、フェーズの Done when: の観測可能な条件の変更、または非目標や移行セクションの変更にあたる重要な編集を行った場合は、スタンプを削除します。編集した人がその行を削除し、再度グリルしたときに改めて記入してください。文言の修正、(#41) や (built YYYY-MM-DD) のようなフェーズ見出しへの注釈の追加、新たな未解決の質問の追加では、スタンプはそのまま残します。ビルド停止時の回答もプランに記録してください。承認済みの外部向けアクションと各テストランナーを、それぞれ確定済みの設計判断の行として記録し、対応待ちのままとする各フェーズには、その見出しの下に、何を待っているかを示す Attended: 行を記載します。無人ランナーはこれらを参照するため、この会話内だけで承認してもランナーには伝わりません。ファイルシステムが使えない場合は、ユーザーが自分で追記できるよう、要約とともにスタンプ行を出力してください。
• それ以外から開始した場合。 大まかなアイデア、誰かの頭の中にある設計、アーキテクチャ、またはPRから始めた場合は、戻すファイルがありません。そのため、決定事項をどこに記録するかを尋ねてください。既存ファイルをその場で更新するか、現在のディレクトリに独立したメモを書くか、何も作成しないかを確認します。促されていないのにファイルを書いたり、保存先を決めつけたりしないでください。grillkitは標準的なプラン文書の形式や docs/plans という慣例を定めていません。

グリルの結果、記録に値するドメイン用語や、後戻りしにくいトレードオフの決定が確定した場合、インストール済みなら記録役はdomainkitです。そうでなければ、用語集の項目またはADRとして記録するよう、確定した決定事項をユーザーに伝えてください。grillkitが担うのは質問であり、その形式を管理することではありません。

結果を公開する

ユーザーはほぼすべてのグリルを、同じ作業を依頼して終えます。計画をコミットし、プッシュし、イシュー本文を更新し、ラベルを切り替えます。これらを1つのアクションとして、1回の確認で提示してください。グリルでファイルが作成されず、イシューも解決されていない場合、または git リポジトリがない場合は、このセクションを省略します。

プレビューを1つ作成します。 該当するアクションをそれぞれ列挙し、関係のない項目は省きます。

• コミット。 パスは、書き換えた計画ファイルと、グリル中に作成した用語集や決定記録です。Conventional Commits の件名の例：docs(plan): grill the <slug> plan。
• プッシュ。 現在のブランチと、その origin のプッシュ先を、通常のファストフォワードとして示します。
• イシュー本文。 グリルで内容を固めたイシューを示します。グリルの起点となったイシュー、または計画で指定されたイシューのいずれかです。変更内容として、確定した決定事項、計画へのリンク、グリルで解決した未解決の質問を示します。
• ラベル。 計画に Grilled: のスタンプがあり、保留中の決定事項がない場合に限り、needs-planning → ready とします。決定事項が保留中の場合、ラベルはそのままにし、プレビューで理由を示します。昇格ルールは issuekit が管理し、イシューに未解決の依存関係が記載されている場合は blocked に変更することがあります。issuekit がない場合は、イシューに未解決の依存関係が記載されていない場合に限り、ready に昇格します。

確認は1回だけ求めます。 「すべて公開」「コミットのみ」「スキップ」の3つの回答を提示します。AskUserQuestion を使える場合は、使用してください。

承認されたアクションを次の順序で実行します。 コミット、プッシュ、イシュー本文、ラベル。

• コミットキットを使い、正確なパスを渡してコミットとプッシュを行います。commitkit がない場合は、git add -- <paths> && git commit -m "<subject>" && git push を実行します。
• issuekit を使ってイシュー本文を編集します。ない場合は、gh issue edit <n> --body-file <file> を実行します。
• issuekit の triage を、対象を指定したリクエスト（#<n> is grilled, mark it ready）として使い、ラベルを昇格させます。ない場合は、gh issue edit <n> --remove-label needs-planning --add-label ready を実行します。

ready は自動で作業を開始するきっかけになるため、ラベルの変更は最後に行います。その作業には、リモート上に計画が必要です。

最初の失敗で停止します。 プッシュが拒否された場合（保護ブランチ、ファストフォワードでない場合、権限がない場合）は、シーケンスを停止します。エラーを報告し、イシュー本文とラベルは変更せず、通常の解決方法を示してください。強制プッシュは決して行わず、ユーザーが依頼していないプルリクエストも決して作成しないでください。

承認されたすべてのアクションが実行されたとき、または最初の失敗が報告され、それ以降のアクションが実行されていないときに、このステップは完了です。

引き継ぎ

このセクションは、手順を示す文体で書きます。1文につき指示は1つとし、能動態、現在形、比喩なしで記述します。

すべてのグリルを同じように締めくくります。兄弟スキルの名前を挙げるのは、そのスキルがインストールされている場合だけとし、それ以外の場合は行動をそのまま説明します。

変更点。 一緒に決めた内容を、それぞれ1行で簡潔にまとめます。提起したものの未解決のままの質問を挙げます。ユーザーが保留した決定は決定ではなく、後続工程でビルドのブロッカーとして再び表面化します。それぞれの決定に、質問済みかデフォルトかを明記します。引き続き人の確認が必要な各フェーズと、ユーザーが承認した各対外アクションを挙げます。

完了した内容。 その場で書き換えた計画ファイルとその Grilled: スタンプ、代わりに書くよう依頼されたファイル、またはユーザーがファイルを辞退した場合は何もなかったことを明記します。結果を公開するの後に、コミット SHA、プッシュしたブランチ、Issue の URL、ラベルを記載します。これらのうちユーザーが省略したもの、または失敗したものがあれば、それを伝えます。

次のステップ。 グリルを終える目的はスタンプにあるため、スタンプによって何が可能になるかを説明します。公開手順で既存の Issue を ready に変更した場合、その Issue はビルド可能です。afkkit を実行する場合は run issue #<n> unattended を指定し、それ以外の場合は issuekit の start <n> で開始し、いずれも使わない場合はブランチを作成して手動でビルドします。プロジェクトが GitHub Issues で作業を管理していて、まだ Issue がない場合、十分に詰めた計画から Issue を作成できます。issuekit はスタンプを読み取り、needs-planning ではなく ready（無人で安全に作業可能）として登録します。プロジェクトが別の場所で作業を管理している場合、または管理場所がない場合は、同じスタンプによって計画のビルドが可能になります。その場合は implementkit と最初のフェーズを挙げます。最初のケースだと決めつけないでください。GitHub を使うプロジェクトでも、バックログを Linear、Jira、またはファイルで管理していることがあります。どこで管理しているかは、プロンプトまたはリポジトリのエージェントガイドファイルに記載されています。計画ファイルがない場合は、決定事項を反映する先として、ビルドそのもの（implementkit）または決定記録（domainkit）を挙げます。どちらも開始しないでください。グリルは共通認識を得た時点で終了です。