ask-matt

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 将其拆分为 tracer bullet 工单，每个工单都声明自己的阻塞关系。在本地跟踪器中，每个工单对应 .scratch/<feature>/issues/ 下的一个文件，手动优先处理阻塞项；在实际跟踪器中，这些关系会变成原生阻塞链接，因此只要某个工单的阻塞项已完成，就可以领取该工单：为每个工单启动一次 /implement，并在每次之间用 /clear 清除上下文。每个工单都是自包含的，因此最后一个工单的上下文可以丢弃。
   • 否 → 就在这里、同一个上下文窗口中使用 /implement。

   无论哪种方式，/implement 都会通过在内部驱动 /tdd（一次完成一个红绿循环）来构建每个问题，最后在提交前运行 /code-review，对差异进行双轴审查（标准 + 规格）。如果你只想在没有完整规格的情况下先编写具体行为的测试再构建，就单独使用 /tdd；如果你想依据确定的标准审查分支或 PR，就单独使用 /code-review。

上下文管理

步骤 1–3 应放在同一个不中断的上下文窗口中（在 /to-tickets 之前不要压缩或清除上下文），这样访谈、规格和工单都能基于相同的思路逐步构建。

之后，每次 /implement 都从全新上下文开始，并以工单为依据开展工作。

这方面的限制是**智能区间**：模型仍能保持敏锐推理能力的窗口范围（最先进的模型约为 150k 个 token）。如果会话在运行 /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。在两个阶段的边界处，你有五种选择，而在整个决策图中，这也是最模糊的判断：

• Continue：保持现状。既不花费，也不损失。
• /clear：清空上下文窗口，适用于这里的内容与接下来的工作无关时。
• /handoff 会写入一个可移植的 Markdown 文件。适用范围很窄：仅用于新工具链、新目录、同事，或在阶段中途分叉出一个附带任务。它带来的是可移植性。
• 子 Agent：将范围明确的任务交给它自己的窗口，并获取报告。
• /compact 会压缩此上下文，并用它为新会话提供初始内容。这是默认选项，位于决策树的末端，而非首选。

请阅读 PHASE-BOUNDARIES.md，了解有序决策树：五个问题、每个分支背后的理由，以及为什么基于一手资料的成本让Continue成为最先排除的选项。请在边界处做出决定；阶段中途则继续工作，或将其余任务拆分给子 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> 分支上，该分支从 main 分出，并在实现问题单中链接到它。它是主流程第 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 会结合你缺少的上下文，用通俗易懂的语言重新表达刚才说过的内容，并使用 CONTEXT.md 中的词汇。它适用于事后补救；/grill-with-docs 则是事前解决方案，因为及早建立共识语言，才能从一开始就避免出现术语。
• /teach：在多个会话中学习一个概念，并使用当前目录作为有状态的工作区。
• /writing-for-agents 是编写供 Agent 阅读的文档的参考指南：技能、AGENTS.md，以及指向其他文档的说明。

前置条件

/setup-matt-pocock-skills：首次运行工程流程前先执行，以配置问题跟踪器、分类标签和其他技能所依赖的文档布局。也支持自定义问题跟踪器。