询问 Matt

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

一个流程是贯穿这些 skills 的一条路径。大多数路径都沿一条主流程推进，并有两条接入路径汇入其中。其余内容要么独立运行，要么是运行在底层的术语层。

主流程：想法 → 交付

大多数工作都会走这条路径。你有一个想法，并希望将它构建出来。

1. /grill-with-docs 通过访谈打磨想法。只要你当前在工作目录中开展工作，就从这里开始：它是有状态的，会将了解到的内容保留在 CONTEXT.md 和 ADR 中。（没有工作目录？请改用 /grill-me，详见“独立使用”部分。两者都运行同一个 /grilling 原语；grill-with-docs 才是会留下书面记录的那一个，因此只要有仓库可以保存这些记录，它就是两者中更好的选择。）
2. 分支：能否在对话中解决所有问题？ 如果某个问题需要一个可运行的答案（状态、业务逻辑，或必须亲眼看到的 UI），就绕道使用原型，并在往返两个方向都通过 /handoff 衔接（原型位于自己的目录中，而这正是 /handoff 的用途；参见“阶段边界”）：

• /handoff 将内容交接出去，然后基于该文件打开一个全新会话，
• /prototype 使用一次性代码回答该问题，
• /handoff 将所得结论交接回来，并在最初的想法线程中引用该结论。

1. 分支：这是需要多个会话的构建吗？

• 是 → /to-spec（将线程转换为规格），然后使用 /to-tickets 将其拆分为曳光弹工单，每个工单都声明自己的阻塞边。在本地跟踪器中，.scratch/<feature>/issues/ 下每个工单各对应一个文件，并由人工按阻塞项优先的顺序处理；在正式跟踪器中，这些边会成为原生阻塞链接，因此只要某个工单的阻塞项已经完成，就可以认领该工单：为每个工单启动 /implement，并在各工单之间使用 /clear 清空上下文。每个工单都是自包含的，因此最后一个工单的上下文可以丢弃。
• 否 → 就在这里、在同一上下文窗口中执行 /implement。

无论哪种情况，/implement 都会在内部驱动 /tdd 来实现每个工单（每次完成一个红—绿切片），然后在提交前运行 /code-review 进行收尾，即对差异开展双轴审查（标准 + 规格）。如果你只是想以测试优先方式构建某个具体行为，而不需要完整规格，请单独使用 /tdd；每当你想以某个固定点为基准审查分支或 PR 时，请单独使用 /code-review。

上下文管理

将步骤 1–3 保持在一个不中断的上下文窗口中（完成 /to-tickets 之前不要压缩或清空），以便访谈、规格和工单都建立在同一套思路之上。随后，每次 /implement 都从全新上下文开始，依据工单开展工作。

这方面的上限是智能区：在这一窗口内（最先进模型约为 150k 个词元），模型仍能进行敏锐的推理。如果某个会话在 /to-tickets 之前就接近该上限，不要在推理能力下降的状态下强行推进；请在最近的阶段边界执行 /compact，然后继续（参见“阶段边界”）。

接入路径

一种先产生工作、再汇入主流程的起始情形。

• 错误和请求不断积压 → /triage。它会让问题依次流经各个分诊角色，并产出可供 agent 处理的问题，之后由 /implement 接手。

分诊只用于处理不是由你创建的问题：错误报告、收到的功能请求，以及任何未经整理就传入的内容。/to-tickets 生成的工单已经可供 agent 处理，因此不要对它们进行分诊。

• 某处出了问题 → /diagnosing-bugs。用于处理棘手情况：一眼无法看透的缺陷、间歇性偶发故障，以及在两个已知正常状态之间悄然引入的回归。在建立紧密反馈循环之前，它拒绝进行理论推测（即一条已经会因*这个*缺陷而报红的命令），然后通过回归测试进行修复。如果事后复盘真正发现的是没有合适的接缝来锁定该缺陷，它会将工作移交给 /improve-codebase-architecture。

• 一项庞大而模糊的工作：全新项目或大型功能构建，规模大到一个会话无法完成 → /wayfinder，这是这里对认知要求最高的流程。当从当前到目的地的路径仍不可见时，它会在问题跟踪器上绘制一张由决策工单构成的共享地图，并逐一解决这些工单，产出决策，而非交付物，直到迷雾消散、路径清晰。如果说 /grill-with-docs 用于打磨你能在一个会话中把握的想法，那么寻路流程则用于你无法在一个会话中把握的想法；它进展更慢、信息密度也更高，因此只在这种情况下使用它，绝不要用于范围明确的功能。

当地图变得清晰时，它会交接，但不会构建：从 /to-spec 汇入主流程，由其将地图中相互关联的决策收束成可构建的计划，然后照常执行 /to-tickets 和 /implement。若让地图直接进入 /implement，就会跳过这一步收束并丢掉相互关联的细节，因此只有当这项工作后来确认确实很小时，才直接进入 /implement。

代码库健康度

不是功能开发，只是维护。

• /improve-codebase-architecture 可在你有空时随时运行，使代码库保持便于 agents 操作的良好状态。它会发掘深化机会；选择其中一个，就会_产生一个想法_，你可以通过 /grill-with-docs 将其带入主流程。它是用于发现候选项的勘察工具；下文的 /codebase-design 则是为选定项进行设计的工作台。

底层术语体系

两个由模型调用的参考项在其他 skills 的*底层*运行，并且各自都是其术语体系的唯一事实来源。当问题在于用词而非流程时，请直接使用它们；或者让上面的 skills 将它们引入。

• /domain-modeling：打磨项目的*领域*语言：质疑模糊的术语，厘清含义过载的词（“账户”一词身兼三职），并将难以撤销的决策记录为一项 ADR。这是 /grill-with-docs 持续推行的一项主动实践，用于让 CONTEXT.md 保持为一份整洁的术语表。
• /codebase-design 是用于设计模块*形态*的深模块术语体系（模块、接口、深度、接缝、适配器、杠杆效应、局部性）：在清晰的接缝处，将大量行为置于一个小型接口之后。/tdd 和 /improve-codebase-architecture 都使用这套术语。

阶段边界

一个阶段是会话中的一段工作：访谈、实现和 QA。在其中两个阶段之间的边界处，你有五种选择，而选择哪一个是整张图中最模糊的决策：

• 继续：留在当前会话。没有成本，也没有损失。
• /clear：当这里的内容对下一步都不重要时，清空窗口。
• /handoff 会生成一个可移植的 Markdown 文件。它的用途很有限：仅用于新的运行环境、新的目录、同事，或在阶段中途分出一个支线任务。它带来的好处是可移植性。
• 子 Agent：将一项范围严格限定的任务发送到其独立的上下文窗口，并获取返回的报告。
• /compact 会压缩当前上下文，并用压缩后的上下文初始化一个全新会话。它是默认选项，位于决策树底部，而不是首先选用的方案。

阅读 [PHASE-BOUNDARIES.md](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 应呈现什么样子。一次性约束的是代码的编写方式，而不是销毁代码的承诺：答案会融入正式代码，而原型本身会作为一手资料保留在从 main 分出的 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 用于补救未能传达清楚的信息。在对话中途、任何其他 skill 内使用它，agent 就会使用 CONTEXT.md 中的词汇，结合你之前缺失的上下文，以通俗易懂的英语重新阐释刚才的话。它用于事后补救；/grill-with-docs 则用于事前预防，因为及早约定共同语言，正是从根本上避免行话出现的办法。
• /teach：在多个会话中学习一个概念，并以当前目录作为有状态工作区。
• /writing-for-agents 是编写供 agents 使用的文档时的参考：skills、AGENTS.md 和被引用的文档。

前置条件

/setup-matt-pocock-skills：在首次运行工程流程之前执行，用于配置其他 skills 所依赖的问题跟踪器、分诊标签和文档布局。自定义问题跟踪器同样可用。