Ask Matt（スキルルーター）

Ask Matt（マットに聞く）

すべてのスキルを覚えてはいられません。だから聞いてください。

スキルの機能を説明したり、ステップをスキップするよう推奨する前に、そのスキルのSKILL.mdを読んでください。ここにあるサマリーはあくまで方向性を示すためのものです。

フローとは、スキルを通る経路のことです。ほとんどの経路は1つのメインフローを辿り、2つのオンランプがそこに合流します。それ以外はスタンドアロンであるか、その下で動作する語彙レイヤーです。

メインフロー：アイデア → 出荷

ほとんどの作業が通るルートです。アイデアがあり、それを構築したい場合に使います。

1. /grill-with-docs は、インタビューによってアイデアを明確にします。ワーキングディレクトリで作業している場合はここから始めてください。これはステートフルであり、学習した内容を GLOSSARY.md と ADR に保持します。（ワーキングディレクトリがない場合は、代わりに /grill-me を使用してください。スタンドアロンで説明します。どちらも同じ /grilling プリミティブを実行します。grill-with-docs は証跡を残すため、リポジトリがある場合には常に優れています。）

2. 分岐：すべての質問を会話で解決できますか？ 実行可能な回答（状態、ビジネスロジック、見て確認する必要があるUI）が必要な質問の場合は、プロトタイプを作成して迂回し、/handoff で双方向に橋渡しします（プロトタイプは独自のディレクトリに置かれ、それがまさに /handoff の目的です。フェーズ境界を参照してください）：

   • /handoff でプロトタイプディレクトリに移行し、そのファイルに対して新しいセッションを開き、
   • /prototype で使い捨てのコードを使用して質問に回答し、
   • /handoff で学んだことを元のアイデアスレッドに戻し、それを参照します。

3. 分岐：これは複数セッションにわたる構築ですか？

   • はい → /to-spec（スレッドを仕様書に変換）、次に /to-tickets でそれをトレーサーブレットチケットに分割し、各チケットはブロッキングエッジを宣言します。その後、チケットを次の2つの方法のいずれかで処理します：
     • /implement をチケットごとに実行し、各チケットの間に /clear でコンテキストをクリアします。ローカルトラッカーでは .scratch/<feature>/issues/ の下にチケットごとに1ファイルとして配置し、ブロッカーが完了したものから手動で処理します。実際のトラッカーでは、エッジはネイティブのブロッキングリンクになり、ブロッカーが完了したチケットはいつでも取得できます。各チケットは自己完結型であるため、最後のチケットのコンテキストは破棄可能です。
     • /implement-spec で仕様全体を1回の実行で処理します。チケットをタスクグラフとして読み取り、準備ができたフロンティア全体で実装サブエージェントを並行して実行し、すべてを1つの統合ブランチにまとめます。自分で各チケットを駆動するよりも、構築をオーケストレーションしたい場合に使用します。
   • いいえ → 同じコンテキストウィンドウ内で、ここで /implement を実行します。

   どちらの場合も、コードは /tdd（1回のレッドグリーンスライスずつ）を駆動することで構築され、/code-review（標準 + 仕様の2軸レビュー）で差分をレビューして完了します。/implement はチケットごとに両方を実行します。/implement-spec の実装者はそれぞれ /tdd を駆動し、統合ブランチに対して1回の /code-review を実行します。完全な仕様なしでテストファーストで具体的な動作を構築したいだけの場合は、/tdd を単独で使用します。また、固定点に対してブランチやPRをレビューしたい場合は、/code-review を単独で使用します。

   作業がプルリクエストとして上がると、/pr が本文を作成します。変更を示す最小のビジュアル、動作することを示すBefore/Afterの証拠、そして一方通行または双方向のドアコールです。これはモデル呼び出しされるため、エージェントはPRを作成するときに自動的に使用します。

4. /retro でループを閉じます。構築後、特に問題が発生した構築後は、セッションを振り返り、コードではなくエージェントの環境（ナビゲーションポインター、自動チェック、/code-review が実施するコーディング標準、ステアリングファイル、ツール）の変更を提案します。機械的なミスは決定論的なチェックに、判断が必要なものはコーディング標準になります。次の構築はより良い環境から始まります。

コンテキスト衛生

ステップ1〜3は1つの切れ目のないコンテキストウィンドウに保持し（/to-tickets まで圧縮やクリアはしない）、グリル、仕様、チケットがすべて同じ思考の上に構築されるようにします。その後、各 /implement はチケットから作業を開始し、新たに開始します。/retro は、振り返るセッション内で、クリアする前に実行します。クリア後は、代わりにそのセッションのログを指定します。

これの限界は**スマートゾーン、つまりモデルがまだ鋭く推論できるウィンドウ（最先端モデルでは約150kトークン）です。セッションが/to-ticketsの前にこのゾーンに近づいた場合は、低下した状態で進めず、最も近いフェーズ境界で/compact** して続行します（フェーズ境界を参照）。

オンランプ

作業を生成し、その後メインフローに合流する開始状況です。

• バグやリクエストが山積み → /triage。トリアージロールを通じてイシューを処理し、エージェント対応可能なイシューを生成します。これらは後で /implement がピックアップします。

  トリアージは自分が作成していないイシューに対してのみ行います。バグレポート、受信した機能リクエスト、生のまま届くものすべてです。/to-tickets が生成したチケットはすでにエージェント対応済みなので、トリアージしないでください。

• 何かが壊れている → /diagnosing-bugs。難しいバグ（一目見ただけではわからない、断続的なフレーク、2つの正常状態の間で忍び込んだリグレッション）に使用します。タイトなフィードバックループ（このバグで既にレッドになる1つのコマンド）ができるまで理論化を拒否し、その後リグレッションテストと共に修正します。修正が入ったら、同じセッションで /retro を実行し、何がバグを防いだかを尋ねます。実際の発見が、それをロックダウンするための良いシームがないことである場合は、/improve-codebase-architecture の仕事です。

• 大きくて曖昧な取り組み：グリーンフィールドプロジェクトや巨大な機能構築で、1セッションでは大きすぎる場合 → /wayfinder。ここで最も認知的に要求されるフローです。ここから目的地への道がまだ見えない場合、イシュートラッカー上に意思決定チケットの共有マップを作成し、それらを1つずつ解決して、霧が押し戻され道が明確になるまで成果物ではなく意思決定を生成します。/grill-with-docs が1セッションで保持できるアイデアを明確にするのに対し、ウェイファインダーは保持できないアイデアのためのものであり、より遅く密度が高いため、適切にスコープされた機能ではなく、まさにそのような場合に取っておきます。

  マップがクリアになったら、構築はせずに引き継ぎます。/to-spec でメインフローに合流します。/to-spec はマップのリンクされた意思決定を構築可能な計画に圧縮し、その後通常どおり /to-tickets と /implement に進みます。マップを直接 /implement にループさせると、その圧縮をスキップしてリンクされた詳細を捨ててしまうため、取り組みが本当に小さいことがわかった場合にのみ、直接 /implement に進んでください。

コードベースの健全性

機能開発ではなく、単なるメンテナンスです。

• /improve-codebase-architecture は、エージェントが操作しやすいコードベースを維持するために、余裕のあるときに実行します。深化の機会を明らかにします。1つを選択すると、/grill-with-docs でメインフローに取り込めるアイデアが生成されます。これは候補を見つける調査であり、/codebase-design（下記）は選択した候補を設計するベンチです。

基礎の語彙

他のスキルの下で動作する、モデルによって呼び出される2つのリファレンスです。それぞれがその語彙の唯一の情報源です。プロセスではなく言葉が問題である場合に直接使用するか、上記のスキルがそれらを呼び出すのに任せます。

• /domain-modeling：プロジェクトのドメイン言語を明確にします。曖昧な用語に挑戦し、過負荷な単語（「アカウント」が3つの仕事をしている）を解決し、元に戻すのが難しい決定をADRとして記録します。これは、/grill-with-docs が GLOSSARY.md をクリーンな用語集に保つために駆動する能動的な規律です。
• /codebase-design は、モジュールの形状を設計するための深いモジュール語彙（モジュール、インターフェース、深さ、シーム、アダプター、レバレッジ、局所性）です。小さなインターフェースの背後に多くの振る舞いがあり、クリーンなシームに配置されます。/tdd と /improve-codebase-architecture の両方がこれを話します。

フェーズ境界

フェーズは、セッション内部の作業の塊です。グリル、実装、QAなどです。2つのフェーズの境界では5つの選択肢があり、その選択はこのマップ全体で最も曖昧な決定です：

• 続行：そのまま続けます。コストはゼロ、損失もゼロです。
• /clear：ウィンドウを空にします。ここにあるものが次に何の関係もない場合に使用します。
• /handoff は、ポータブルなMarkdownファイルを書き出します。狭い用途です。新しいハーネス、新しいディレクトリ、同僚、またはフェーズ途中でのサイドタスクのフォーク専用です。得られるものはポータビリティです。
• サブエージェント：厳密にスコープされたタスクを独自のウィンドウに送信し、レポートを取得します。
• /compact はこのコンテキストを圧縮し、それをシードとして新しいセッションを開始します。ツリーの一番上ではなく一番下にあるデフォルトです。

PHASE-BOUNDARIES.md を読んで、順序付けられたツリーを確認してください。5つの質問、各ブランチの背後にある理由、そしてプライマリソースのコストがなぜ続行を最初に除外すべきものにするかについて説明しています。決定は境界で行います。フェーズ途中では、続行するか、残りをサブエージェントに分割します。

スタンドアロン

メインフローから完全に外れています。

• /grill-me：/grill-with-docs と同じ執拗なインタビューですが、ステートレスです。ローカルには何も保存せず、GLOSSARY.md も作成しません。ワーキングディレクトリで作業していない場合（計画、設計、文章、リポジトリの下にないものすべてを明確にする場合）に使用します。ワーキングディレクトリにいる場合は、代わりに /grill-with-docs を使用してください。同じインタビューを実行し、証跡を残すため、厳密に優れています。
• /grilling はインタビュープリミティブそのものです。ラウンド、フロンティア、事実はエージェントの仕事であり、決定はあなたのものです。/grill-me と /grill-with-docs は2つの名前付きの入り口であり、/triage、/wayfinder、/improve-codebase-architecture はすべて内部でこれを実行します。ラッパーなしでインタビューだけが必要な場合に直接使用します。
• /prototype は、1つの設計上の質問に答える小さな使い捨てプログラムです。この状態モデルは正しいか、このUIはどのように見えるべきか。使い捨てとはコードの書き方に対する制約であり、破壊する約束ではありません。答えは実際のコードに折り込まれ、プロトタイプ自体は prototype/<name> ブランチ（mainから分岐）にプライマリソースとして保持され、実装イシューから参照されます。これはメインフローのステップ2での迂回ですが、設計上の質問を書面上で解決するのが難しい場合はいつでも使用します。
• /research：読む作業をバックグラウンドエージェントに委任します。プライマリソースに対して質問を調査し、引用付きのMarkdownファイルをリポジトリに残します。エージェントが読んでいる間も作業を続けられます。生成されるファイルは、/grill-with-docs でメインフローに取り込むためのものです。研究は思考を養うものであり、置き換えるものではないからです。
• /to-questionnaire は、あなたを妨げているものがあなたの頭やコードベースではなく、他の誰かの頭の中にある場合に使用し、その人に記入してもらうアンケートを作成します。これは /grill-me の逆です。あなたに主題についてインタビューする代わりに、送信先（誰に送るのか、何を返してもらう必要があるのか）についてインタビューし、ギャップに向けて質問を向けます。返ってきたものは、/grill-with-docs または /to-spec の材料になります。
• /wizard は人間にしかできないステップのためのものです。インフラのプロビジョニング、認証情報やCIシークレットの設定、馴染みのないサードパーティのダッシュボードのクリック操作、1回限りの移行やカットオーバーの実行などです。各URLを開き、各値をキャプチャし、.env やGitHubシークレットに書き込むインタラクティブなbashスクリプトを生成するため、手順をエージェントに毎回説明し直す必要がなくなります。モデル呼び出しされるため、エージェントはあなただけが通過できる壁にぶつかった瞬間に自動的に使用します。エージェントが自分でできる場合はそうすべきであり、これは人間が実際にループ内にいる場合のためのものです。
• /wait-what は、メッセージが届かなかった場合の修正手段です。会話の途中で、他のスキルの内部で使用します。エージェントは、あなたが欠いていたコンテキストを使って、平易な英語で、GLOSSARY.md の語彙を使用して、今言ったことを言い直します。これは事後的に機能します。/grill-with-docs は事前の治療法です。早期に合意された共通言語こそが、専門用語がそもそも出現するのを防ぐからです。
• /teach：現在のディレクトリをステートフルなワークスペースとして使用し、複数のセッションにわたって概念を学習します。
• /writing-for-agents は、エージェントが消費するドキュメント（スキル、AGENTS.md、参照先ドキュメント）を作成するためのリファレンスです。

前提条件

/setup-matt-pocock-skills：最初のエンジニアリングフローの前に実行し、他のスキルが前提とするイシュートラッカー、トリアージラベル、ドキュメントレイアウトを設定します。カスタムイシュートラッカーも動作します。