Ask Matt

你不必记住每一个技能，所以来问。

在说明某个技能的作用或建议跳过某一步之前，先阅读该技能的 SKILL.md：这里的摘要仅用于定位。

流程（flow）是穿过技能的一条路径。大多数路径沿一条主干流程行进，两条入口匝道汇入其中。其余的都是独立技能，或者是在底层运行的词汇层。

主干流程：想法 → 交付

大多数工作走的路线。你有一个想法，想把它建出来。

1. /grill-with-docs：通过盘问打磨想法。只要你在工作目录里就从这里开始：它是有状态的，会把学到的东西保存在 GLOSSARY.md 和 ADR 中。（没有工作目录？用 /grill-me，见"独立技能"。两者跑的是同一个 /grilling 原语；grill-with-docs 是会留下书面痕迹的那个，所以只要有仓库可以留痕迹，它就是更好的选择。）

2. 分支：所有问题都能在对话中解决吗？ 如果某个问题需要一个可运行的答案（状态、业务逻辑、必须亲眼看到的 UI），就绕道原型，由 /handoff 双向桥接（原型住在自己的目录里，这正是 /handoff 的用武之地，见"阶段边界"）：

   • /handoff 跳出去，然后针对那个文件开一个新会话，
   • /prototype 用一次性代码回答问题，
   • /handoff 把你学到的东西带回来，并在原始想法线程中引用它。

3. 分支：这是多会话构建吗？

   • 是 → /to-spec（把对话变成 spec），然后 /to-tickets 把它拆成示踪子弹式 ticket，每个都声明自己的阻塞边。接着用两种方式之一推进 ticket：
     • /implement 逐个 ticket 实现，每个之间用 /clear 清空上下文。在本地跟踪器上，每个 ticket 是 .scratch/<feature>/issues/ 下的一个文件，按阻塞优先的顺序人工推进；在真实跟踪器上，阻塞边变成原生阻塞链接，所以任何阻塞项已完成的 ticket 都可以被领取。每个 ticket 自包含，所以上一个的上下文可以丢弃。
     • /implement-spec 一次性实现整份 spec。它把 ticket 读成一张任务图，在可领取的前沿上并行运行实施者子代理，把一切落到一条集成分支上。当你更想编排整个构建、而不是亲自逐张驱动 ticket 时用它。
   • 否 → 就在同一个上下文窗口里 /implement。

   无论哪种方式，代码都靠驱动 /tdd（一次一个红-绿切片）来构建，并以 /code-review 收尾，对 diff 做双轴审查（标准 + 规格）。/implement 对每张 ticket 各跑一遍这两步；/implement-spec 的每个实施者各自驱动 /tdd，然后在集成分支上跑一次 /code-review。只想在没有完整 spec 的情况下测试优先地构建一个具体行为时，单独用 /tdd；任何时候想对照固定点审查分支或 PR，单独用 /code-review。

   当工作要以 PR 提交时，/pr 负责塑造 PR body：能说清变更的最小可视化、证明其可行的 before/after 证据、以及单向门/双向门的判断。它是模型调用的，所以 agent 每次写 PR 都会主动拿起来用。

4. /retro 闭合这个循环。一次构建之后（尤其是跑偏的那种），它会回顾整个会话，为 agent 的环境（而非代码）提出改动建议：导航指针、自动化检查、/code-review 执行的编码规范、引导文件、工具。机械性错误变成确定性检查；判断题变成编码规范。下一次构建就从更好的环境开始。

上下文卫生

把步骤 1–3 保持在一个不间断的上下文窗口里（在 /to-tickets 之前不要压缩或清空），这样盘问、spec 和 ticket 都建立在同一个思考之上。之后每次 /implement 从 ticket 出发、重新开始。在它所回顾的那次会话里、清空之前运行 /retro；清空之后，就把它指向那次会话的日志。

这里的上限是**智能区**：模型仍能敏锐推理的窗口（最先进模型约 150k token）。如果会话在 /to-tickets 之前就逼近它，不要在劣化的状态下硬撑：在最近的阶段边界 /compact 然后继续（见"阶段边界"）。

入口匝道

一个会产生工作的起点场景，然后并入主干流程。

• bug 和请求堆积 → /triage。它让 issue 走过分类角色，产出 agent 就绪的 issue，之后由 /implement 接手。

  分类只适用于不是你创建的 issue：bug 报告、外来的功能请求、任何以原始形态到达的东西。/to-tickets 产出的 ticket 已经是 agent 就绪的，所以不要分类它们。

• 有东西坏了 → /diagnosing-bugs。用于那些难啃的：一眼看不出的 bug、间歇性偶发（flake）、在两个已知正常状态之间悄悄溜进来的回归。在拥有紧反馈循环之前它拒绝空谈理论（一条已经能对这个 bug 变红的命令），然后用回归测试修复。修复完成后，在同一会话中运行 /retro，追问什么本可以避免这个 bug；如果真正的发现是缺少合适的接缝来锁定它，就由 /improve-codebase-architecture 处理。

• 一项庞大而模糊的工作：绿地项目或大型功能构建，大到一次会话装不下 → /wayfinder，这是这里认知负荷最高的流程。当从这里到目的地的路还看不见时，它在 issue 跟踪器上绘制一张由决策 ticket 组成的共享地图，一次解决一个：产出决策，而非交付物，直到迷雾被推后、道路清晰。/grill-with-docs 打磨的是你能在一次会话里 hold 住的想法，wayfinder 则是为你 hold 不住的想法准备的：它更慢、更密，所以只留给这种情况，绝不要用于范围明确的功能。

  当地图清晰时，它交接，不构建：在 /to-spec 并入主干流程，把地图上相互关联的决策折叠成可构建的计划，然后照常 /to-tickets 和 /implement。把地图直接循环进 /implement 会跳过这个折叠，把关联的细节丢掉，所以只有当工作量确实很小的时候才直接进 /implement。

代码库健康

不是功能工作：是维护。

• /improve-codebase-architecture：只要有空就跑一跑，让代码库保持对 agent 友好的可作业状态。它揭示深化机会；挑一个就产生一个想法，你可以带着它从 /grill-with-docs 进入主干流程。它是找出候选者的勘测；/codebase-design（见下）是你设计所选方案的工作台。

底层词汇

两个模型调用的参考，运行在其他技能之下：各自是其词汇的唯一真实来源。当问题出在词语而不是流程时，直接伸手去拿；或者让上面的技能把它们拉进来。

• /domain-modeling：打磨项目的领域语言：挑战含糊的术语、消解过载的词（"account" 身兼三职）、把难以逆转的决策记为 ADR。它是 /grill-with-docs 驱动、让 GLOSSARY.md 保持为干净词汇表的主动训练。
• /codebase-design：设计模块形态的深度模块词汇（module、interface、depth、seam、adapter、leverage、locality）：在干净的接缝后面，用一个小接口承载大量行为。/tdd 和 /improve-codebase-architecture 都讲这套语言。

阶段边界

阶段是会话内的一块工作：盘问、实现、QA。在两个阶段的边界上你有五个选项，而在这张地图里，选哪个是最模糊的决定：

• 继续（Continue）：原地不动。不花任何代价，也不损失任何东西。
• /clear：清空窗口，当这里没有任何东西与下一步相关时。
• /handoff：写一个可移植的 markdown 文件。用途窄：只用于新的环境、新的目录、同事，或在阶段中途分叉一个子任务。它买到的是可移植性。
• 子代理（Subagent）：把一个范围严格的任务送进它自己的窗口，拿回一份报告。
• /compact：压缩当前上下文，用它播种一个新会话。它是默认项，位于树的底部而不是最先伸手可及的地方。

读 PHASE-BOUNDARIES.md 了解排序的决策树：五个问题、每条分支背后的理由，以及为什么一手来源的成本让继续成为第一个被排除的选项。在边界处做决定；阶段中途，要么继续，要么把剩余部分拆成子代理。

独立技能

完全脱离主干流程。

• /grill-me：与 /grill-with-docs 同样锲而不舍的盘问，但无状态：不向本地保存任何东西，不构建 GLOSSARY.md。当你不在工作目录中工作时用它：打磨计划、设计、一篇文章，任何底下没有仓库的东西。如果在工作目录里，就用 /grill-with-docs 代替：它跑同样的盘问并且留下书面痕迹，所以严格来说更好。
• /grilling：盘问原语本身：轮次、前沿，事实是 agent 的工作而决策是你的。/grill-me 和 /grill-with-docs 是两条具名的入口，/triage、/wayfinder 和 /improve-codebase-architecture 都在内部跑它。只有当你想盘问、但不要任何外壳时才直接伸手去拿。
• /prototype：一个回答某个设计问题的小型一次性程序：这个状态模型感觉对吗，或者这个 UI 应该长什么样。一次性是对代码写法的约束，而不是销毁它的承诺：答案折进真实代码，原型本身作为一手来源保留在 main 之外名为 prototype/<name> 的分支上，由实现 issue 指向它。它是主干流程第 2 步的绕道，但任何时候一个设计问题难以在纸上定案，都可以用它。
• /research：把阅读跑腿委托给后台 agent：它对照一手来源调查一个问题，然后在仓库里留下一份带引用的 Markdown 文件。它读的时候你继续干活。它产出的文件是要带进主干流程、在 /grill-with-docs 用的；研究喂养思考，不取代思考。
• /to-questionnaire：当挡着你的东西不在你脑子里、也不在代码库里，而在别人脑子里时，这个技能给他们写一份问卷来填。它是 /grill-me 的反面：不是盘问你关于主题的事，而是盘问你关于发送的事（发给谁、你需要拿回什么），然后把问题对准缺口。拿回来的东西是 /grill-with-docs 或 /to-spec 的素材。
• /wizard：用于只有人能做的步骤：配置基础设施、设置凭据或 CI 密钥、在一个陌生的第三方仪表盘上点点点、跑一次性的迁移或切换。它生成一个交互式 bash 脚本，逐个打开 URL、捕获每个值，写进 .env 和 GitHub secrets，这样这个流程就不再需要每次向 agent 重新解释一遍。模型调用，所以 agent 一撞上只有你能通过的墙就会伸手去拿。如果 agent 自己能做，它就该自己做；这是给真正需要人在环里的场景的。
• /wait-what：对一条没被接住的消息的矫正。在任何其他技能内部、对话中途使用它，agent 会用你缺失的上下文、用 GLOSSARY.md 的词汇，以大白话重新讲一遍它刚说过的话。它是事后补救；/grill-with-docs 是事前的解药，因为早早约定共同语言才不会让行话出现。
• /teach：跨多个会话学习一个概念，把当前目录当作有状态的工作空间。
• /writing-for-agents：编写 agent 消费的文档的参考：skills、AGENTS.md、被指向的文档。

前置条件

/setup-matt-pocock-skills：在第一次工程流程之前运行，配置其他技能所依赖的 issue 跟踪器、分类标签和文档布局。自定义 issue 跟踪器也可以。