Ask Matt

你不会记得每一个技能，所以就问吧。

一个流程是穿过这些技能的一条路径。大多数路径都沿着一条主流程行进，还有两条引入匝道汇入其中。其余的要么是独立技能，要么是在底层运行的一层词汇。

主流程：想法 → 交付

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

1. /grill-with-docs — 通过访谈打磨想法。每当你在一个工作目录中工作时，从这里开始：它是有状态的，把学到的东西保留在 CONTEXT.md 和 ADR 中。（没有工作目录？用 /grill-me——见「独立技能」。两者都运行同一个 /grilling 原语；grill-with-docs 是会留下书面记录的那个，这使它在有仓库可供落笔的任何时候都是两者中更好的一个。）

2. 分支——你能在对话中解决每一个问题吗？ 如果某个问题需要一个可运行的答案（状态、业务逻辑、你必须亲眼看到的 UI），就绕道去做一个原型，两个方向都由 /handoff 搭桥（原型活在它自己的目录里，而这正是 /handoff 的用途——见「阶段边界」）：

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

3. 分支——这是一个跨多会话的构建吗？

   • 是 → /to-spec（把线程变成规格），然后 /to-tickets 把它拆成曳光弹式工单，每个都声明其阻塞边。在本地跟踪器上，那是 .scratch/<feature>/issues/ 下每个工单一个文件，靠手工按阻塞优先顺序推进；在真实跟踪器上，这些边成为原生的阻塞链接，于是任何阻塞项已完成的工单都可以被领取——为每个工单启动 /implement，在每个工单之间 /clear 上下文。每个工单都是自包含的，所以上一个工单的上下文是可丢弃的。
   • 否 → 就在此处、在同一个上下文窗口里 /implement。

   无论哪种方式，/implement 都通过在内部驱动 /tdd 来构建每个工单——一次一个红-绿切片——然后通过运行 /code-review 收尾，这是在提交前对 diff 做的双轴审查（标准 + 规格）。当你只想不带完整规格地、测试先行地构建某个具体行为时，单独使用 /tdd；当你想针对某个固定基点审查一个分支或 PR 时，单独使用 /code-review。

上下文卫生

把第 1–3 步保持在一个不间断的上下文窗口里——在 /to-tickets 之前不要压缩或清空——这样拷问、规格和工单就都建立在同一份思考之上。此后每个 /implement 都从头开始，以工单为工作依据。

对此的限制是**聪明区间**：模型仍能敏锐推理的那个窗口（在最先进的模型上约 150k tokens）。如果一个会话在 /to-tickets 之前就逼近它，不要在退化状态下硬撑——在最近的阶段边界处 /compact，然后继续（见「阶段边界」）。

引入匝道

一种会产生工作、随后汇入主流程的起始情形。

• bug 和请求堆积起来了 → /triage。它让工单在分诊角色中流转，产出可供 agent 处理的工单，稍后由 /implement 接手。

  分诊只针对不是你创建的工单——bug 报告、进来的功能请求、任何原始到来的东西。/to-tickets 产出的工单已经是可供 agent 处理的了，所以不要对它们做分诊。

• 有东西坏了 → /diagnosing-bugs。针对那些难缠的：一眼看不出来的 bug、间歇性的抖动、在两个已知良好状态之间悄悄潜入的回归。它在拥有一个紧凑的反馈循环（一条已经能在这个 bug 上变红的命令）之前拒绝做任何理论推测——然后用一个回归测试来修复。它的事后复盘会在真正的发现是「没有好的接缝来把 bug 锁死」时，交接给 /improve-codebase-architecture。

• 一项庞大、迷雾重重的工作——一个全新项目或一次庞大的功能构建，大到一个会话装不下 → /wayfinder，这里认知负担最重的流程。当从此处到目的地的路径尚不可见时，它在工单跟踪器上绘制一张由决策工单构成的共享地图，并逐个解决它们——产出的是决策，而非交付物——直到迷雾被推开、路径清晰。/grill-with-docs 打磨的是你能在一个会话里把握住的想法，而 wayfinder 针对的是你把握不住的那种想法——而且它更慢、更密，所以只在正是那种情况下动用它，绝不用于一个界定良好的功能。

  当地图明朗后，它做交接，不做构建：在 /to-spec 处汇入主流程，把地图上相互链接的决策收拢成一份可构建的计划，然后照常 /to-tickets 和 /implement。把地图直接接进 /implement 会跳过那次收拢，把相互链接的细节丢掉——只有当这项工作最终真的很小的时候，才直接去 /implement。

代码库健康

不是功能工作——是维护保养。

• /improve-codebase-architecture — 每当你有空闲时间、想让代码库保持对 agent 友好、便于其中操作时运行。它浮现出深化机会；挑选一个就生成一个想法，你可以把它带进主流程的 /grill-with-docs。它是那份找出候选项的勘测；/codebase-design（见下文）则是你用来设计所选那个候选项的工作台。

底层词汇

两个模型调用型的参考文件，它们运行在其他技能的底层——各自是其词汇的唯一真理来源。当词语（而非流程）成为问题时直接动用它们；或者让上面的技能把它们拉进来。

• /domain-modeling — 打磨项目的领域语言：质疑一个模糊的术语，理清一个含义过载的词（"account" 同时干三份活），把一个难以逆转的决策记录成 ADR。它是 /grill-with-docs 所驱动的、让 CONTEXT.md 保持为一份干净词汇表的主动准则。
• /codebase-design — 用于设计一个模块形状的深模块词汇（模块、接口、深度、接缝、适配器、杠杆、局部性）：在一个干净的接缝处、用一个小接口承载大量行为。/tdd 和 /improve-codebase-architecture 都讲这套词汇。

阶段边界

一个阶段是会话内部的一块工作——拷问、实现、QA。在其中两个之间的边界处，你有五个选项，而在它们之间做选择是整张地图里最模糊的决策：

• 继续 — 留在原地。不花代价，不丢东西。
• /clear — 清空窗口，当这里的东西对接下来毫无意义时。
• /handoff — 写一个可移植的 markdown 文件。适用面窄：只针对新的 harness、新目录、同事，或在阶段中途分叉一个旁支任务。它换来的是可移植性。
• 子 agent — 把一个界定紧凑的任务发送到它自己的窗口，并取回一份报告。
• /compact — 压缩当前上下文，并用它引导一个全新的会话。这是默认项，位于决策树底部而非首选。

阅读 PHASE-BOUNDARIES.md 了解那棵有序的决策树——五个问题、每个分支背后的推理，以及为什么一手来源的代价使得继续成为要最先排除的那一个。在边界处做这个决策；阶段中途，要么继续，要么把剩下的拆分给子 agent。

独立技能

完全在主流程之外。

• /grill-me — 与 /grill-with-docs 同样不留情面的访谈，但是无状态的：它不在本地保存任何东西，也不构建 CONTEXT.md。当你不在工作目录中工作时动用它——打磨一份计划、一个设计、一段文字，任何底下没有仓库的东西。如果你在工作目录里，就改用 /grill-with-docs：它运行同样的访谈却留下书面记录，所以它严格来说是更好的那个。
• /grilling — 访谈原语本身：一轮轮进行、前沿、事实是 agent 的活儿而决策是你的活儿。/grill-me 和 /grill-with-docs 是两个具名的入口，而 /triage、/wayfinder 和 /improve-codebase-architecture 都在内部运行它。只有当你想要不带任何外壳的访谈时才直接动用它。
• /resolving-merge-conflicts — 逐块处理进行中的合并或变基冲突，依据追溯到各方一手来源的意图来解决，而不是靠挑选行，然后完成该操作。它从不运行 --abort。独立、脱离所有流程：当你已经身处冲突中途时动用它。
• /prototype — 一个小的、用完即弃的程序，回答一个设计问题：这个状态模型感觉对不对，或者这个 UI 该长什么样。用完即弃是对代码怎么写的一种约束，而不是要销毁它的承诺：答案会折叠进真实代码，而原型本身作为一份一手来源被保留在主线之外的 prototype/<name> 分支上，由实现工单指向它。它是主流程第 2 步里的那个绕道，但任何时候一个设计问题在纸上难以定夺时都可以动用它。
• /research — 把阅读的跑腿活儿委派给一个后台 agent：它针对一手来源调查一个问题，然后在仓库里留下一个带引用的 Markdown 文件。在它阅读时你继续干活。它产出的文件是要带进主流程 /grill-with-docs 的东西——研究喂养思考，而不是取代思考。
• /to-questionnaire — 当挡住你的东西既不在你脑子里、也不在代码库里，而在别人脑子里时，这个技能给他们写一份问卷去填。它是 /grill-me 的反向操作：它不就主题访谈你，而是就这次发送访谈你——它要发给谁、你需要拿回什么——并把问题瞄准那个缺口。回来的东西是给 /grill-with-docs 或 /to-spec 用的素材。
• /wizard — 针对只有人类才能采取的步骤：配置基础设施、设置凭据或 CI 密钥、点击穿过陌生的第三方仪表盘、执行一次性迁移或切换。它生成一个交互式 bash 脚本，打开每个 URL、捕获每个值、把它写进 .env 和 GitHub 密钥——这样这套流程就不再是每次都要向 agent 重新解释的东西。模型调用型，所以 agent 一撞上只有你才能越过的墙就会主动动用它。如果 agent 自己就能做，它就该自己做；这是用于人类确实身处环中的场合。
• /wait-what — 一条消息没传达到位时的纠正手段。在对话中途、在任何其他技能内部使用它，agent 就会带上你之前缺失的上下文，用平实的英语、用 CONTEXT.md 的词汇，重新表述它刚说过的东西。它是事后起作用的；/grill-with-docs 是前置的疗法，因为早早商定的共同语言正是从一开始就阻止行话出现的东西。
• /teach — 跨多个会话学习一个概念，把当前目录当作一个有状态的工作区。
• /writing-for-agents — 编写供 agent 消费的文档（技能、AGENTS.md、被指向的文档）的参考。

前置条件

/setup-matt-pocock-skills — 在你第一次跑工程流程之前运行，以配置其他技能所假定的工单跟踪器、分诊标签和文档布局。自定义工单跟踪器也能用。