ask-matt

Ask Matt

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

フローとは、スキルを通る経路です。ほとんどの経路はメインフローに沿って進み、一部のオンランプが合流します。それ以外はすべて、単独で使うものか、下層で動作する語彙レイヤーです。

メインフロー：アイデア → ship

作業の大半がたどる経路です。アイデアがあり、それを形にしたい場合に使います。

1. /grill-with-docs — インタビューを通じてアイデアを磨きます。作業ディレクトリ内で作業している場合は、必ずここから始めてください。状態を保持し、学んだ内容を CONTEXT.md と ADR に記録します。（作業ディレクトリがない場合は、/grill-me を使ってください。Standalone を参照。どちらも同じプリミティブ /grilling を実行します。grill-with-docs はディスク上に記録を残すため、記録先となるリポジトリがある場合はこちらが最適です。）
2. 分岐 — 会話だけですべての疑問を解決できますか？ 実行可能な答えが必要な疑問（状態、ビジネスロジック、実際に見る必要がある UI）がある場合は、prototype に寄り道し、両方向を /handoff でつなぎます（prototype は専用ディレクトリに置かれます。それこそが /handoff の用途です。Phase boundaries を参照）。
   • /handoff で引き継いでから、そのファイルを対象に新しいセッションを開きます。
   • /prototype で使い捨てコードを書き、疑問への答えを見つけます。
   • 学んだ内容を /handoff で戻し、元のアイデアのスレッドから参照します。
3. 分岐 — 複数セッションにまたがるビルドですか？
   • はい → /to-spec でスレッドを仕様に変換し、続いて /to-tickets で、それぞれにブロッキングエッジを明記した tracer-bullet チケットに分割します。ローカルトラッカーでは、.scratch/<feature>/issues/ の下にチケットごとのファイルを作成し、手動でブロッカーから順に作業します。本格的なトラッカーでは、エッジがネイティブなブロッキングリンクになるため、ブロッカーが解決済みのチケットを誰でも着手できます。チケットごとに /implement を実行し、チケット間ではコンテキストに /clear を実行します。各チケットは自己完結しているため、最後のチケットのコンテキストは破棄できます。
   • いいえ → このまま同じコンテキストウィンドウで /implement を実行します。

どちらの場合も、/implement は各チケットを、内部で /tdd を実行しながら構築します。つまり、red-green のスライスを一度に1つずつ進め、コミット前に差分を二軸（Standards + Spec）でレビューする /code-review を実行して完了します。完全な仕様なしで、具体的な振る舞いだけをテストファーストで実装したい場合は /tdd を単独で使います。確かな基準に照らしてブランチや PR をレビューしたい場合は、いつでも /code-review を単独で使います。

コンテキストの衛生管理

手順 1〜3 は、中断のない1つのコンテキストウィンドウ内で進めてください。思考を引き継いでインタビュー、仕様、チケットを作成できるよう、/to-tickets が終わるまでは圧縮したりクリアしたりしないでください。その後の各 /implement は、チケットを起点に新しいコンテキストで開始します。

この上限となるのが smart zone です。モデルが明晰に推論できるウィンドウ（最先端モデルでは約150kトークン）のことです。/to-tickets の前にセッションがこの上限に近づいた場合、性能が落ちた状態で無理に続けず、最も近いフェーズ境界で /compact を実行して続行してください（Phase boundaries を参照）。

開始点

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

• バグやリクエストが積み上がっている → /triage。トリアージの各ロールを通じて issue を進め、エージェント対応の issue を作成します。その後、/implement がそれを取り込みます。

  トリアージは、あなたが作成していない issue のみに使います。バグ報告や寄せられた機能リクエストなど、未整理の状態で届くものが対象です。/to-tickets が作成したチケットはすでにエージェント対応なので、トリアージしないでください。

• 何かが壊れた → /diagnosing-bugs。難しい問題に使います。最初の調査では見つからないバグ、断続的に発生するフレーク、既知の正常な2つの状態の間に紛れ込んだリグレッションなどです。このバグですでに red になるコマンド、つまり短いフィードバックループを用意するまでは、原因を推測しません。その後、リグレッションテストを追加して修正します。真の発見が、バグを封じ込める適切な接合点が存在しないことだと分かった場合は、事後分析から /improve-codebase-architecture に引き継ぎます。

• 大きくて見通しの立たない取り組み — 新規プロジェクトや、1回のセッションでは大きすぎる機能開発 → /wayfinder。ここで最も認知負荷の高いフローです。現在地から目的地までの道筋がまだ見えないとき、issue トラッカー上に decision ticket の共有マップを作成し、それらを1つずつ解決します。作り出すのは成果物ではなく決定事項です。霧が晴れ、道筋が明確になるまで続けます。/grill-with-docs が1回のセッションに収まるアイデアを磨くのに対し、wayfinder は収まらないアイデアのためのものです。より時間がかかり、密度も高いため、本当に必要な場合に限って使い、範囲が明確な機能には使わないでください。

  マップが明確になったら、構築せずに引き継ぎます。/to-spec でメインフローに合流し、マップ内でリンクされた決定事項を構築可能な計画にまとめます。その後は通常どおり /to-tickets、/implement と進みます。マップから直接 /implement に進むと、この整理を飛ばしてリンクされた詳細を失います。取り組みが本当に小規模だと分かった場合に限り、直接 /implement に進んでください。

コードベースの健全性

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

• /improve-codebase-architecture — 自由な時間があればいつでも実行し、エージェントが作業しやすいコードベースを維持してください。改善の機会を提示します。そのうち1つを選ぶと、メインフローの /grill-with-docs に持ち込める_アイデアが生まれます_。これは候補を見つけるための調査であり、選んだものを設計する作業台は**/codebase-design**（以下）です。

基盤となる用語

他のスキルの内部で動作する、モデルが呼び出す2つのリファレンスです。それぞれが自身の用語に関する唯一の信頼できる情報源です。問題がプロセスではなく言葉にある場合は直接参照するか、上記のスキルから呼び出させてください。

• /domain-modeling — プロジェクトのドメイン言語を磨きます。曖昧な用語を問い直し、複数の役割を持つ単語（3つの異なる意味で使われる「アカウント」など）を整理し、覆すのが難しい決定を ADR として記録します。これは、/grill-with-docs が CONTEXT.md を明確な用語集に保つために用いる実践です。
• /codebase-design — 深いモジュール（モジュール、インターフェース、深さ、接合点、アダプター、レバレッジ、局所性）の用語を使って、モジュールの形を設計します。つまり、小さなインターフェースの背後に多くの振る舞いを持たせ、明確な接合点を設けます。/tdd と /improve-codebase-architecture はこの用語体系を使います。

フェーズの境界

フェーズとは、セッション内の作業の一区切りです。審査、実装、QA などがこれに当たります。2つのフェーズの境界では5つの選択肢があり、そのどれを選ぶかが、このマップ全体で最も判断の曖昧な部分です。

• Continue — そのまま続けます。コストも損失もありません。
• /clear — ここにある情報が次の作業に関係ない場合は、ウィンドウを空にします。
• /handoff — 持ち運び可能な Markdown ファイルを書き出します。用途は限定的で、新しいハーネス、新しいディレクトリ、同僚への引き継ぎ、またはフェーズの途中で別タスクを切り分ける場合に使います。これによって得られるのは移植性です。
• Subagent — スコープを明確に定めたタスクを自身のウィンドウに割り当て、レポートを受け取ります。
• /compact — このコンテキストを圧縮し、その内容を引き継いだ新しいセッションを開始します。実質的なデフォルトですが、最初の選択肢ではなく、ツリーの下の方にあります。

順序立てられたツリー、5つの質問、各分岐の理由、そして一次ソースを確認するコストのためにContinueが最初に除外される理由については、PHASE-BOUNDARIES.mdを参照してください。判断は境界で行い、フェーズの途中ではそのまま続けるか、残りをサブエージェントに分けます。

単独で使うもの

メインフローにはまったく含まれません。

• /grill-me — /grill-with-docs と同じ容赦ないインタビューですが、ステートレスです。ローカルには何も保存せず、CONTEXT.md も作成しません。作業ディレクトリで作業していない場合に使ってください。計画や設計、文章など、リポジトリを伴わないものを磨くときに適しています。作業ディレクトリで作業しているなら、/grill-with-docs を使ってください。同じインタビューを実行し、その記録も残すため、こちらのほうが間違いなく優れています。
• /grilling — インタビューそのもののプリミティブです。ラウンドやフロンティア、事実の整理はエージェントが行い、決定するのはあなたです。/grill-me と /grill-with-docs は名前付きの2つの入り口であり、/triage、/wayfinder、/improve-codebase-architecture はすべて内部でこれを実行します。ラッパーなしでインタビューだけを行いたい場合に限り、直接使ってください。
• /resolving-merge-conflicts — 進行中のマージまたはリベースの競合を、各側の一次資料にたどって意図を確認し、行を選ぶのではなく、ハンクごとに解決してから処理を完了します。--abort は決して実行しません。単独で使い、ほかのフローには含まれません。すでに競合の解決作業に入っているときに使ってください。
• /prototype — 設計上の問いに答えるための、小さく使い捨てのプログラムです。この状態モデルでよいか、あるいはこの UI をどうすべきか、といった問いに答えます。使い捨てであることはコードの書き方に関する制約であり、削除を約束するものではありません。答えは実際のコードに反映され、プロトタイプ自体もメインから分岐した prototype/<name> ブランチに一次資料として保存され、実装イシューから参照されます。メインフローのステップ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-leandrocfe-skills — 最初のエンジニアリングワークフローを実行する前に起動し、他のスキルが前提とする課題トラッカー、トリアージラベル、ドキュメントのレイアウトを設定してください。カスタムの課題トラッカーも使用できます。