ask-matt

リポジトリに関する作業を始める前に、../../WORK-ROUTING.md を読んでください。これは、プロジェクト文書、レーンの選択、計画の担当、作業の締めくくりに関する共通のルーティング情報源です。

Matt に聞く

すべてのスキルを覚えているわけではないので、聞いてください。

フローとは、スキルを経由する道筋です。ほとんどの道筋は、1 つのメインフローに沿って進み、2 つの導入経路がそこに合流します。それ以外は単独で使うものか、その下層で機能する語彙レイヤーです。

メインフロー：アイデア → リリース

ほとんどの作業が進む経路です。アイデアを形にしたいときに使います。

1. /grill-with-docs — インタビュー形式でアイデアを磨きます。作業ディレクトリ内で作業する場合は、いつでもここから始めてください。これは状態を保持し、学んだ内容を CONTEXT.md と ADR に記録します。（作業ディレクトリがない場合は /grill-me を使ってください。Standalone を参照してください。どちらも同じ /grilling プリミティブを実行します。grill-with-docs は記録を残すため、記録先となるリポジトリがある場合はこちらのほうが適しています。）

2. 分岐 — 会話だけですべての疑問を解決できますか？ 実行可能な回答が必要な疑問（状態、ビジネスロジック、実際に見なければならない UI）がある場合は、プロトタイプを経由します。/handoff を使って両方向につなぎます（プロトタイプは独自のディレクトリに置かれます。まさにそのための /handoff です。Phase boundaries を参照してください）。

   • /handoff で引き継ぎ、そのファイルを使って新しいセッションを開始します。
   • /prototype を使って、使い捨てコードで疑問への答えを確かめます。
   • 学んだ内容を /handoff で元に戻し、最初のアイデアのスレッドから参照します。

3. 分岐 — 複数のセッションにまたがる開発ですか？

   • はい → /to-spec でスレッドを仕様書にまとめ、次に /to-tickets でトレーサーバレットチケットに分割します。各チケットにはブロッキング依存関係を明記します。ローカルトラッカーでは、.scratch/<feature>/issues/ 配下にチケットごとのファイルを 1 つ作成し、手作業でブロッカーから順に進めます。実際のトラッカーでは、依存関係がネイティブのブロッキングリンクになるため、ブロッカーがすべて完了したチケットを誰でも着手できます。チケットごとに /implement を開始し、その間に /clear でコンテキストをクリアします。各チケットは自己完結しているため、最後のチケットのコンテキストは破棄できます。
   • いいえ → このまま同じコンテキストウィンドウで /implement を実行します。

   どちらの場合も、/implement は内部で /tdd を実行し、赤から緑へと一度に 1 つずつ進めて各イシューを実装します。その後、コミット前に /code-review を実行し、差分を基準（Standards + Spec）に照らして 2 つの軸からレビューして締めくくります。完全な仕様書なしで、具体的な振る舞いをテストファーストで実装したい場合は /tdd を単独で使ってください。ブランチや PR を定められた基準に照らしてレビューしたい場合は、いつでも /code-review を単独で使ってください。

コンテキストの管理

ステップ 1〜3 は、1 つの途切れないコンテキストウィンドウ内で進めてください。グリリング、仕様書、チケットがすべて同じ思考の流れを引き継げるよう、/to-tickets が終わるまではコンテキストを圧縮したりクリアしたりしないでください。

ただし、ここには**スマートゾーン**という限界があります。これは、モデルが鋭い推論を維持できるウィンドウ（最先端モデルで約 150k トークン）です。/to-tickets の前にセッションがこの限界に近づいた場合は、劣化した状態で無理に続けないでください。最も近いフェーズの境目で /compact を実行してから続けます（Phase boundaries を参照）。

開始地点

作業を生み出し、メインフローに合流する出発点です。

• バグや要望が積み上がっている → /triage。課題をトリアージの各役割に沿って進め、エージェントがすぐに取りかかれる課題を作成します。それを後から /implement が引き継ぎます。

  トリアージの対象は、自分が作成していない課題だけです。バグ報告、届いた機能要望など、生の状態で届いたものが該当します。/to-tickets が作成したチケットはすでにエージェントがすぐに取りかかれる状態なので、トリアージしないでください。

• 何かが壊れている → /diagnosing-bugs。難しいバグに対応します。ひと目ではわからないバグ、断続的に発生する不安定な動作、正常と確認された2つの状態の間に紛れ込んだリグレッションなどが対象です。短いフィードバックループ、つまり、このバグですでに失敗するコマンドが用意できるまで、仮説を立てることを拒みます。その後、リグレッションテストを追加して修正します。事後分析で、バグを確実に封じ込めるための適切な継ぎ目がないことが真の問題だと判明した場合は、/improve-codebase-architecture に引き継ぎます。

• 先の見えない大規模な取り組み — 新規プロジェクトや、1回のセッションでは大きすぎる大規模な機能開発 → /wayfinder。ここにあるフローの中で、最も高度な認知能力を要します。現在地から目的地への道筋がまだ見えないとき、課題トラッカー上に意思決定チケットからなる共有マップを作成し、ひとつずつ解決します。生み出すのは成果物ではなく、意思決定です。先の霧が晴れて道筋が見えるまで続けます。1回のセッションで把握できるアイデアを深めるのが /grill-with-docs なのに対し、wayfinder は1回のセッションでは把握しきれないアイデアのためのものです。時間がかかり、内容も濃密なので、まさにそのような場合に限って使い、範囲が明確な機能には決して使わないでください。

  マップが明らかになったら、引き継ぎはしますが、実装はしません。メインフローの /to-spec に合流させ、マップ上の関連する意思決定を、実装可能な計画にまとめます。その後は通常どおり /to-tickets、/implement と進めます。マップから直接 /implement に進むと、この整理を飛ばして関連する詳細が失われます。取り組みが実際には小規模だとわかった場合に限り、直接 /implement に進んでください。

コードベースの健全性

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

• /improve-codebase-architecture — コードベースをエージェントが扱いやすい状態に保つため、時間が空いたときにいつでも実行してください。深化の機会を見つけ、そのひとつを選ぶと、メインフローの /grill-with-docs に持ち込める アイデアが生まれます。候補を見つける調査役がこちらです。選んだ候補を設計する作業台は、下記の /codebase-design です。

その下にある用語体系

他のスキルの基盤として動作する、モデルから呼び出される2つのリファレンスです。それぞれの用語体系における唯一の信頼できる情報源です。プロセスではなく言葉が問題のときに直接参照するか、上記のスキルから呼び出させてください。

• /domain-modeling — プロジェクトのドメイン言語を明確にします。曖昧な用語に疑問を投げかけ、複数の意味で使われている語（3つの役割を担う「account」など）を整理し、後戻りが難しい決定をADRとして記録します。これは、CONTEXT.md を明確な用語集に保つために /grill-with-docs が用いる、実践的な手法です。
• /codebase-design — 深いモジュールを設計するための語彙体系です（module、interface、depth、seam、adapter、leverage、locality）。明確な継ぎ目に、小さなインターフェースの背後に多数の振る舞いを備えるモジュールの形状を設計します。/tdd と /improve-codebase-architecture は、どちらもこの語彙体系を使います。

フェーズの境界

フェーズとは、セッション内の作業のまとまりです。調査、実装、QA などが該当します。フェーズ間の境界では、5 つの選択肢があり、どれを選ぶかは、この全体図の中でもっとも判断が曖昧なところです。

• 続行 — そのまま続けます。コストはかからず、失うものもありません。
• /clear — 次の作業にここでの情報が何も関係しない場合に、ウィンドウを空にします。
• /handoff — 持ち運び可能な Markdown ファイルを書き出します。用途は限定されており、新しいハーネス、新しいディレクトリ、同僚、またはフェーズの途中でのサイドタスクの分岐にのみ使います。これによって得られるのは、持ち運びやすさです。
• サブエージェント — 範囲を厳密に限定したタスクを独自のウィンドウに割り当て、レポートを受け取ります。
• /compact — このコンテキストを圧縮し、それをもとに新しいセッションを開始します。最初に選ぶのではなく、選択ツリーの末尾にあるデフォルトです。

順序立てられたツリー、5 つの質問、各分岐の根拠、そして一次情報のコストを考えると、まず続行を選択肢から外すべき理由については、PHASE-BOUNDARIES.md をお読みください。判断するのは境界に達したときです。フェーズの途中では、続行するか、残りをサブエージェントに分割してください。

単独で使うもの

メインフローから完全に独立しています。

• /grill-me — /grill-with-docs と同じく徹底的に質問しますが、ステートレスです。ローカルには何も保存せず、CONTEXT.md も作成しません。作業ディレクトリにいないときに使います。計画や設計、文章など、リポジトリを伴わないあらゆるものを磨き上げるのに適しています。作業ディレクトリにいる場合は、代わりに /grill-with-docs を使ってください。同じ質問を行いながら記録も残すため、こちらのほうが確実に優れています。
• /grilling — 質問そのものを行う基本機能です。質問のラウンド、探るべき最前線、事実の確認はエージェントの役割で、意思決定はあなたが行います。/grill-me と /grill-with-docs は、この機能を使うための名前付きの入口であり、/triage、/wayfinder、/improve-codebase-architecture は内部でこの機能を実行します。ラッパーを介さずに質問だけを行いたい場合に、直接使ってください。
• /resolving-merge-conflicts — 進行中のマージまたはリベースで発生した競合を、各側の主要なソースをたどって意図を確認し、行を選ぶのではなく意図に基づいてハンクごとに解決し、処理を完了します。--abort は決して実行しません。すべてのフローから独立しているため、すでに競合の解決中である場合に使ってください。
• /prototype — 設計上の疑問に答える、小規模で使い捨てのプログラムです。この状態モデルはしっくりくるか、この UI はどのような見た目にすべきか、といった疑問に答えます。使い捨てという制約はコードの書き方に関するもので、破棄する約束ではありません。答えは実際のコードに取り込まれ、プロトタイプ自体も、main から分岐した prototype/<name> ブランチ上に主要なソースとして保持され、実装の issue から参照されます。メインフローのステップ 2 にある寄り道ですが、設計上の疑問を紙上で解決しにくいときはいつでも使ってください。
• /research — バックグラウンドエージェントに調査作業を委任します。エージェントは主要なソースに基づいて質問を調査し、引用付きの Markdown ファイルをリポジトリに残します。調査中も作業を続けられます。生成されたファイルは、/grill-with-docs でメインフローに持ち込むためのものです。調査は思考を支援するものであり、思考に取って代わるものではありません。
• /to-questionnaire — あなたの頭の中にもコードベースにもなく、他の人の中にあるものが作業の障害になっている場合、その人に記入してもらう質問票を作成します。これは /grill-me の逆です。テーマについてあなたに質問するのではなく、送付について、つまり誰に送るのか、何を返してほしいのかを確認し、情報の不足を埋める質問を作ります。返ってきた内容は、/grill-with-docs または /to-spec で使う資料になります。
• /wizard — インフラのプロビジョニング、認証情報や CI シークレットの設定、使い慣れていないサードパーティのダッシュボードの操作、単発の移行や切り替えなど、人間にしかできない手順のための機能です。各 URL を開き、各値を取得して .env と GitHub シークレットに書き込む、対話型の bash スクリプトを生成します。これにより、毎回エージェントに手順を説明し直す必要がなくなります。モデルから呼び出されるため、エージェントだけでは越えられない壁にぶつかった時点で、エージェントはこれを使います。エージェント自身で実行できるなら実行すべきです。これは、人間が本当に関与する必要がある場面のためのものです。
• /wait-what — メッセージが伝わらなかったときに使う修正機能です。他のスキルの実行中を含め、会話の途中で使うと、エージェントはあなたに欠けていた文脈を補って、直前に伝えた内容を平易な英語で説明し直します。その際は CONTEXT.md の語彙を使います。これは事後に使う機能です。事前に使う対策は /grill-with-docs です。早い段階で共通の言葉を合意しておけば、専門用語がそもそも出てこなくなります。
• /teach — 現在のディレクトリを状態を保持する作業場所として使い、複数のセッションにわたって概念を学びます。
• /writing-for-agents — エージェントが読むドキュメント（スキル、AGENTS.md、参照先として指定されたドキュメント）の執筆ガイドです。

前提条件

/setup-matt-pocock-skills — 他のスキルが前提とする issue トラッカー、トリアージ用ラベル、ドキュメントのレイアウトを設定するため、最初のエンジニアリングフローの前に実行してください。カスタムの issue トラッカーも使用できます。