Razsk/VideoStudio

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つの統合ブランチに統合します。自分で各チケットを駆動するよりも、ビルドをオーケストレーションしたい場合に使用してください。
   • いいえ → 同じコンテキストウィンドウ内で、ここで /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。トリアージロールを通じてIssueを処理し、エージェント対応のIssueを生成します。これらは後で /implement が取得します。

  トリアージは自分が作成していないIssue（バグレポート、受信した機能リクエスト、未整理で届くもの）にのみ使用します。/to-tickets が生成したチケットはすでにエージェント対応なので、トリアージしないでください。

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

• 巨大で曖昧な取り組み: グリーンフィールドプロジェクトや巨大な機能ビルドで、1セッションには大きすぎる → /wayfinder。ここで最も認知的負荷が高いフローです。現在地から目的地への道筋がまだ見えない場合、Issueトラッカー上に決定チケットの共有マップを作成し、それらを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 が GLOSSARY.md をクリーンな用語集に保つために駆動する能動的な規律です。
• /codebase-design は、モジュールの形状を設計するための深いモジュール語彙（モジュール、インターフェース、深さ、シーム、アダプター、レバレッジ、局所性）です。小さなインターフェースの背後、クリーンなシームに多くの振る舞いを持たせます。/tdd と /improve-codebase-architecture はどちらもこれを話します。

フェーズ境界

フェーズとは、セッション内の作業の塊（グリル、実装、QA）です。2つのフェーズの境界では5つの選択肢があり、その中から選択することはこのマップ全体で最も曖昧な判断です:

• 続行: そのまま進む。コストはゼロ、失うものはなし。
• /clear: ウィンドウを空にする。次に何をするにも、ここにあるものが重要でない場合。
• /handoff はポータブルなマークダウンファイルを書き込みます。狭い用途: 新しいハーネス、新しいディレクトリ、同僚、またはフェーズ途中でのサイドタスクのフォーク専用。得られるのはポータビリティです。
• サブエージェント: 厳密にスコープされたタスクを独自のウィンドウに送信し、レポートを受け取ります。
• /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はどのように見えるべきか）に答えるための、小さな使い捨てプログラムです。使い捨てはコードの書き方に対する制約であり、破壊を約束するものではありません。答えは実際のコードに折り込まれ、プロトタイプ自体は main からの prototype/<name> ブランチに一次情報源として保持され、実装Issueから参照されます。これはメインフローのステップ2での迂回ですが、設計上の質問を紙の上で解決するのが難しい場合はいつでも使用してください。
• /research: 読書の足場仕事をバックグラウンドエージェントに委任します。一次情報源に対して質問を調査し、引用付きのマークダウンファイルをリポジトリに残します。エージェントが読んでいる間も作業を続けてください。生成されたファイルは、メインフローの /grill-with-docs に持ち込むためのものです。リサーチは思考を養うものであり、置き換えるものではないからです。
• /to-questionnaire は、あなたをブロックしているものがあなたの頭やコードベースではなく他の誰かの頭にある場合に使用し、その人に記入してもらうアンケートを生成します。これは /grill-me の逆です。トピックについてあなたにインタビューする代わりに、送信先（誰に送るのか、何を返してもらう必要があるのか）についてあなたにインタビューし、質問をギャップに向けます。戻ってくるものは /grill-with-docs または /to-spec の材料です。
• /wizard は人間のみが実行できるステップ（インフラのプロビジョニング、認証情報やCIシークレットの設定、馴染みのないサードパーティダッシュボードの操作、一度きりの移行やカットオーバーの実行）のためのものです。各URLを開き、各値をキャプチャし、.env とGitHubシークレットに書き込むインタラクティブなbashスクリプトを生成するため、その手順をエージェントに毎回説明し直す必要がなくなります。モデル起動型なので、エージェントは自分だけでは通過できない壁にぶつかった瞬間にこれを呼び出します。エージェントが自分で実行できるのであれば、そうすべきです。これは人間が本当にループ内にいる場合のためのものです。
• /wait-what は、メッセージが伝わらなかった場合の修正手段です。会話の途中で、他のスキル内で使用すると、エージェントはあなたが不足していたコンテキストを使って、わかりやすい英語で、GLOSSARY.md の語彙を使って、今言ったことを言い直します。これは事後的に機能します。/grill-with-docs は事前の治療法です。なぜなら、早期に合意された共有言語こそが、専門用語がそもそも出現するのを防ぐからです。
• /teach: 現在のディレクトリをステートフルなワークスペースとして使用し、複数のセッションにわたって概念を学習します。
• /writing-for-agents は、エージェントが消費するドキュメント（スキル、AGENTS.md、参照されるドキュメント）を書くためのリファレンスです。

前提条件

/setup-matt-pocock-skills: 最初のエンジニアリングフローの前に実行して、他のスキルが想定するIssueトラッカー、トリアージラベル、ドキュメントレイアウトを設定します。カスタムIssueトラッカーでも機能します。