ask-matt

问 Matt

你不需要记住每个 skill，所以直接问。

Flow 是穿过 skills 的一条路径。大多数路径沿着一条 main flow 前进，两个 on-ramps 会并入它。其他内容要么是 standalone，要么是在下层运行的 vocabulary layer。

主流程：idea -> ship

这是大多数工作的路线：你有一个想法，并希望把它构建出来。

1. /grill-with-docs - 通过访谈打磨想法。在 working directory 中工作时从这里开始：它是 stateful 的，会把学到的内容保存在 GLOSSARY.md 和 ADRs 中。（没有 working directory？用 /grill-me，见「独立 skills」。两者都运行同一个 /grilling primitive；grill-with-docs 是会留下文档痕迹的版本，只要有 repo 可记录，它就是两者中更好的那个。）

2. 分支 - 能否在对话中解决所有问题？ 如果某个问题需要可运行的答案（state、business logic，或必须亲眼看到的 UI），就通过 prototype 绕行，并用 /handoff 在两个方向桥接（prototype 住在自己的目录里，这正是 /handoff 的用途，见「Phase 边界」）：

   • /handoff 导出，然后基于该文件打开 fresh session；
   • /prototype 用 throwaway code 回答问题；
   • /handoff 把学到的内容带回来，并在原始 idea thread 中引用它。

3. 分支 - 这是 multi-session build 吗？

   • 是 -> /to-spec（把 thread 变成 spec），再用 /to-tickets 拆成 tracer-bullet tickets，每个 ticket 声明 blocking edges。然后从以下两种方式中选一种来推进这些 tickets：
     • 逐 ticket 运行 /implement，并在 tickets 之间用 /clear 清空 context。Local tracker 在 .scratch/<feature>/issues/ 下每 ticket 一个文件，手动按 blockers-first 处理；真实 tracker 用 native blocking links，因此 blockers 已完成的 ticket 都可领取。每个 ticket 都是自包含的，因此最后一个 ticket 的 context 可以丢弃。
     • 用 /implement-spec 一次运行实现整份 spec。它把 tickets 读作 task graph，在 ready frontier 上并行运行 implementer subagents，并把全部成果落到一条 integration branch 上。当你更想编排这次 build、而不是亲自逐个驱动 ticket 时，就选它。
   • 否 -> 在当前 context window 里直接运行 /implement。

   无论哪种方式，代码都通过驱动 /tdd 来构建（一次一个 red-green slice），并用 /code-review 收尾，也就是对 diff 做 Standards + Spec 双轴 review。/implement 会在每个 ticket 上运行这两者；/implement-spec 的每个 implementer 各自驱动 /tdd，它再对 integration branch 运行一次 /code-review。只想在没有完整 spec 的情况下 test-first 构建一个具体 behavior 时，单独用 /tdd；想按固定点 review branch 或 PR 时，单独用 /code-review。

   当工作以 pull request 的形式提上去时，/pr 负责塑形 PR 正文：展示这次变更的最小 visual、证明它可用的 before/after 证据，再加上一次单向门还是双向门的判断。它是 model-invoked 的，所以 agent 每次写 PR 都会伸手用它。

4. /retro 闭合循环。一次 build 之后，尤其是一次走了弯路的 build，它会回看整个 session，建议改动 agent 的 environment，而不是代码：navigation pointers、automated checks、/code-review 强制执行的 coding standards、steering files、tooling。机械性错误变成 deterministic checks；judgement calls 变成 coding standards。下一次 build 由此从更好的 environment 出发。

Context 卫生

步骤 1 到 /to-tickets 要留在 同一个未中断的 context window 中；不要 compact 或 clear，这样 grilling、spec 和 tickets 才能建立在同一组思考之上。之后每个 /implement 都从 fresh session 开始，只基于对应 ticket 工作。在 clear 之前，在被回看的那个 session 里运行 /retro；clear 之后，改为让它读取该 session 的 log。

限制来自 smart zone：在该窗口（最新模型大约 150k tokens）内，模型还能保持敏锐推理。如果 session 在 /to-tickets 前接近这个区间，不要硬撑降级状态；在最近的 phase boundary 用 /compact，然后继续（见「Phase 边界」）。

入口匝道

起点会生成工作，然后并入 main flow。

• Bugs 和 requests 堆积 -> /triage。它通过 triage roles 推进 issues，并产出 agent-ready issues，之后由 /implement 领取。

  Triage 只用于 不是你创建的 issues：bug reports、incoming feature requests，以及任何原始进入的内容。/to-tickets 产出的 tickets 已经是 agent-ready，不要再 triage。

• Something's broken -> /diagnosing-bugs。用于难处理的问题：第一眼看不出的 bug、间歇性 flake、夹在两个 known-good states 之间的 regression。它在拥有 tight feedback loop 前拒绝空想，也就是一个已经能在 这个 bug 上变红的命令；然后用 regression test 修复。修复到位后，在同一个 session 里运行 /retro，追问什么本可以预防这个 bug；如果真正的发现是没有好 seam 能把 bug 锁住，那就是 /improve-codebase-architecture 的工作。

• 巨大而模糊的 effort：greenfield project 或巨大 feature build，一个 session 装不下 -> /wayfinder，这是这里认知负担最重的 flow。当从当前位置到 destination 的路还看不见时，它在 issue tracker 上绘制 decision tickets 的 shared map，逐个解决，产出 decisions, not deliverables，直到 fog 被推开、路径清晰。/grill-with-docs 用于一个 session 能装下的想法，wayfinder 用于装不下的想法；它更慢、更密集，所以只应留给确实如此的 effort，绝不要用于范围明确的 feature。

  Map 清晰后，它会 hand off，而不是 build：先进入 /to-spec，把 map 中相互链接的 decisions 收束成可构建计划，然后照常使用 /to-tickets 和 /implement。让 map 直接循环进入 /implement 会跳过这次收束并丢掉相互链接的细节；只有当 effort 后来发现确实很小时，才直接进入 /implement。

コードベースの健全性

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

• /improve-codebase-architecture - 時間があるときに実行し、エージェントが扱いやすいコードベースを維持します。改善の余地を明らかにします。そのうちの1つを選ぶとアイデアが生成され、メインフローの /grill-with-docs に持ち込めます。候補を探すのがこのスキルの役割です。/codebase-design（以下を参照）は、選んだ候補を設計するための作業台です。

基礎となる語彙

モデルから呼び出される2つのリファレンスは、ほかのスキルの下位で動作し、それぞれ固有の語彙の信頼できる唯一の情報源です。問題がワークフローではなく言葉に関するものであれば、これらを直接使ってください。また、上位のスキルから自動的に呼び出すこともできます。

• /domain-modeling - プロジェクトの ドメイン 用語を磨きます。曖昧な用語に異議を唱え、複数の意味を持つ言葉（たとえば、1つの「account」が3つの役割を担っている場合）を整理し、覆すのが難しい決定を ADR として記録します。これは、/grill-with-docs が GLOSSARY.md の用語集を整理された状態に保つために用いる、継続的な規律です。
• /codebase-design - ディープモジュールの語彙（module、interface、depth、seam、adapter、leverage、locality）を使って、モジュールの 形 を設計します。つまり、明確な接合部にある小さなインターフェースの背後に多くの振る舞いを集約します。/tdd と /improve-codebase-architecture は、どちらもこの語彙を使います。

フェーズの境界

フェーズとは、セッション内の作業の一区切りです。要件の掘り下げ、実装、QA などが該当します。それらの間の境界では5つの選択肢があります。このマップ全体の中でも、どれを選ぶかが最も判断しにくい決定です。

• Continue - そのまま続けます。コストはかからず、何も失いません。
• /clear - ここにある内容が次の作業には何も関係ない場合、コンテキストウィンドウをクリアします。
• /handoff - 持ち運び可能な Markdown ファイルを書きます。用途は限定的で、新しいハーネス、新しいディレクトリ、同僚に引き継ぐ場合、またはフェーズの途中でサイドタスクを分岐させる場合にだけ使います。これにより、持ち運びやすさが得られます。
• Subagent - 範囲を絞ったタスクを専用のコンテキストウィンドウに渡し、レポートを受け取ります。
• /compact - このコンテキストを圧縮し、要約をもとに新しいセッションを開始します。これはデフォルトの選択肢で、ツリーの最初にあるのではなく、最下部にあります。

順序付けされたツリーについては、PHASE-BOUNDARIES.md を読んでください。そこでは、5つの問い、各分岐の背後にある理由、そして一次情報源を扱うコストを考えると、Continueが最初に除外すべき選択肢となる理由を説明しています。判断するのは境界です。フェーズの途中では、続行するか、残りの作業をサブエージェントに分割してください。

独立したスキル

メインフローの完全に外側にあります。

• /grill-me - /grill-with-docs と同じ継続的なインタビューですが、ステートレスです。ローカルには何も保存せず、GLOSSARY.md も作成しません。作業ディレクトリにいないときに使います。計画、設計、文章など、リポジトリが受け皿にならないものを磨く用途です。作業ディレクトリにいる場合は、代わりに /grill-with-docs を使ってください。同じインタビューを実行し、文書として記録を残すため、厳密にはこちらのほうが適切です。
• /grilling - インタビューの基本機能そのものです。反復、フロンティア、事実確認はエージェントの仕事であり、決定するのはあなたです。/grill-me と /grill-with-docs は名前付きの入口であり、/triage、/wayfinder、/improve-codebase-architecture は内部でこれを実行します。ラッパーなしでインタビューしたい場合にだけ、直接使ってください。
• /prototype - 設計上の問いに答えるための、小さな使い捨てプログラムです。たとえば、この状態モデルで問題ないか、あるいはこの UI をどのようなものにすべきかを確かめます。「使い捨て」とはコードの書き方に関する制約であり、破棄する約束ではありません。答えは実際のコードに取り込まれ、プロトタイプ自体はメインブランチの外にある prototype/<name> ブランチに一次情報源として残され、実装の issue から参照されます。メインフローの第2ステップから分岐する方法ですが、紙上では解決しにくい設計上の問いであれば、どんなものにも直接使えます。
• /research - 読み込み作業をバックグラウンドエージェントに委任します。エージェントは一次情報源に基づいて問いを調査し、引用を含む Markdown ファイルをリポジトリに残します。調査中も作業を続けられます。成果物はメインフローの /grill-with-docs に持ち込んでください。調査は思考の材料を提供しますが、思考そのものに代わるものではありません。
• /to-questionnaire - あなたの頭の中にもコードベースにもなく、ほかの人の頭の中にあることが作業の妨げになっている場合、このスキルが相手に記入してもらう質問票を作成します。これは /grill-me の逆です。対象に関するあなたの考えを尋ねるのではなく、送る相手（誰に送るか、何を受け取りたいか）についてあなたに尋ね、そのギャップに合わせた質問を作成します。返ってきた内容は、/grill-with-docs または /to-spec の素材になります。
• /wizard - インフラのプロビジョニング、認証情報や CI シークレットの設定、使い慣れていないサードパーティーのダッシュボードでの操作、一度限りのマイグレーションや切り替えなど、人間にしかできない手順に使います。対話型の bash スクリプトを生成し、各 URL を開いて値を取得し、.env と GitHub secrets に書き込みます。これにより、エージェントにその手順を毎回説明し直す必要がなくなります。これはモデルから呼び出されるため、エージェントはあなたにしか越えられない壁にぶつかると呼び出します。エージェント自身でできることは、エージェント自身が行うべきです。このスキルは、実際に人間がループに参加する場面で使います。
• /wait-what - 話がうまく伝わらなかったときに使う、メッセージの言い直し機能です。会話の途中や、ほかのスキルの実行中に使うと、エージェントは不足していたコンテキストを補い、平易な言葉と GLOSSARY.md の語彙を使って、直前の発言を言い直します。これは事後の対処です。根本的な解決策は、先回りして使う /grill-with-docs です。早い段階で共有の言葉を一緒に決めておけば、専門用語が飛び交うのを防げます。
• /teach - 現在のディレクトリを状態を保持する作業領域として使い、複数のセッションにわたって概念を学びます。
• /writing-for-agents - エージェントが利用するドキュメント（スキル、AGENTS.md、参照先のドキュメントなど）を書くためのリファレンスです。

前提条件

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