ask-matt

询问 Matt

你不可能记住每项技能，所以遇到问题就问。

在说明某项技能的作用或建议跳过某个步骤之前，请先阅读该技能的 SKILL.md：这里的摘要仅供了解概况。

流程是穿过各项技能的一条路径。大多数路径沿着一条主流程前进，另外两条入口路径会汇入其中。其他内容则是独立的，或是在底层运行的词汇层。

主流程：构想 → 交付

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

1. /grill-with-docs 通过访谈打磨构想。只要你在工作目录中工作，就从这里开始：它会保留状态，将学到的内容记录在 GLOSSARY.md 和 ADR 中。（没有工作目录？请改用 /grill-me，详见「独立使用」部分。两者运行的是同一个 /grilling 基础流程；grill-with-docs 会留下书面记录，因此只要有可供记录的仓库，它就是更好的选择。）

2. 分支：你能在对话中解决所有问题吗？ 如果某个问题需要可运行的答案（状态、业务逻辑、必须亲眼查看的 UI），就通过原型绕道，并在两个方向上都使用 /handoff 衔接（原型位于自己的目录中，而这正是 /handoff 的用途；参见「阶段边界」）：

   • 使用 /handoff 转出，然后针对该文件开启一个新会话，
   • 使用 /prototype 编写临时代码来回答问题，
   • 使用 /handoff 传回学到的内容，并在原始构想的讨论线程中引用。

3. 分支：这是一个需要多个会话完成的构建任务吗？

   • 是 → 使用 /to-spec（将讨论线程转成规范），然后使用 /to-tickets 将其拆分为示踪弹式工单，每个工单都声明其阻塞依赖边。接着通过以下三种方式之一处理工单：
     • 对每个工单使用 /implement，并在每个工单之间使用 /clear 清除上下文。使用本地跟踪器时，每个工单对应 .scratch/<feature>/issues/ 下的一个文件，人工按阻塞项优先的顺序处理；使用实际跟踪器时，这些依赖边会成为原生阻塞链接，因此只要某个工单的阻塞项已完成，就可以领取该工单。每个工单都是独立完整的，因此最后一个工单的上下文可以丢弃。
     • 使用 /implement-spec 在一次运行中完成整个规范。它会将工单读取为一个任务图，并行运行负责实现的子 Agent 来处理就绪的前沿任务，并将所有内容合并到一个集成分支。如果你更愿意编排整个构建过程，而不是亲自逐个处理工单，就选择它。
     • 使用单独安装的 /orchestrate 处理子问题确实相互独立的父问题。它会在各自的 worktree 上为每个子问题启动一个 /implement Agent，并负责机械性的后续工作（排序、传递、合并顺序、清理），但绝不会重新切分工作；/to-tickets 发布的子问题就是要处理的任务包。它需要原生子问题功能，因此只能用于 GitHub，不能用于本地文件。
   • 否 → 就在这里、同一个上下文窗口中使用 /implement。

   无论选择哪种方式，代码都会通过运行 /tdd（一次完成一个红绿循环）来构建，并以 /code-review 收尾，对差异进行双轴审查（标准 + 规范）。/implement 会针对每个工单运行这两个流程；/implement-spec 的各个实现 Agent 都会运行 /tdd，并对集成分支运行一次 /code-review。如果你只想先编写测试，再实现一个具体行为，而不需要完整规范，就单独使用 /tdd；如果你想根据一个固定基准审查分支或 PR，就单独使用 /code-review。

   当工作以拉取请求的形式提交时，/pr 会完善正文内容：用最精简的视觉材料展示改动，提供改动前后的有效证据，并判断这是单向门还是双向门。它由模型调用，因此 Agent 每次编写 PR 时都会使用它。

4. /retro 完成闭环。构建结束后，尤其是进展不顺时，它会回顾整个会话，并建议改进 Agent 的环境，而不是代码：导航指引、自动化检查、/code-review 执行的编码标准、指导文件和工具。机械性错误会转化为确定性检查；判断性事项会转化为编码标准。这样，下一次构建就能从更完善的环境开始。

上下文卫生

请将第 1–3 步保留在同一个不间断的上下文窗口中（在 /to-tickets 完成之前不要压缩或清空），这样拷问、规格说明和工单都基于同一套思路。之后每次 /implement 都从头开始，依据工单工作。在清空上下文之前，请在回顾对象所在的会话中运行 /retro；清空之后，则让它指向该会话的日志。

这里的限制是 智能区：即模型仍能敏锐推理的上下文窗口（当前最先进的模型约为 150k tokens）。如果会话在 /to-tickets 之前接近该上限，不要在能力下降的状态下硬撑；请在最近的阶段边界处运行 /compact，然后继续（参见阶段边界）。

入口

由某种起始情境产生工作，再汇入主流程。

• Bug 和需求不断堆积 → /triage。它会推动问题经过各个分类角色，并生成可供 Agent 处理的问题，之后由 /implement 接手。

  分类只适用于你并未创建的问题：Bug 报告、传入的功能需求，以及任何未经加工的原始内容。由 /to-tickets 生成的工单已经可供 Agent 处理，因此不要对它们进行分类。

• 出现故障 → /diagnosing-bugs。适用于较难的情况：初看无从下手的 Bug、间歇性出现的不稳定问题，以及在两个已知正常状态之间悄然引入的回归。它在获得一个紧凑的反馈回路（即一条已经能针对此个 Bug 报错的命令）之前，拒绝进行理论推测，然后通过回归测试进行修复。修复完成后，在同一会话中运行 /retro，探讨什么能够防止该 Bug；如果真正的结论是缺少可以锁定它的良好接缝，则应交由 /improve-codebase-architecture 处理。

• 庞大且模糊的工作：全新项目或规模过大、无法在单个会话内完成的大型功能开发 → /wayfinder，这是此处认知要求最高的流程。当从当前位置到达目标的路径尚不清晰时，它会在问题跟踪器上绘制一张共享地图，其中包含若干决策工单，并逐一解决它们。它产出的是决策，而非交付物，直到迷雾散去、路径清晰为止。而 /grill-with-docs 用于打磨可以在单个会话中掌握的想法，wayfinder 则面向无法在单个会话中掌握的想法。它更慢也更密集，因此应只在确有必要时使用，而非用于范围明确的功能。

  地图清晰之后，它的任务是交接，而非构建：在 /to-spec 处汇入主流程。/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），用于设计模块的形状：在一个干净的 seam 之后，用一个小的 interface 封装大量行为。/tdd 和 /improve-codebase-architecture 都使用这套词汇。

阶段边界

阶段是会话中的一段工作，例如梳理需求、实现、QA。在两个阶段的边界处，你有五种选择。在它们之间做选择是整张图中最模糊的决策：

• Continue：保持现状。没有成本，也不会丢失任何内容。
• /clear：清空窗口，适用于接下来的工作与此处内容无关的情况。
• /handoff 会写出一个可移植的 markdown 文件。适用范围很窄，仅用于新的 harness、新的目录、同事，或在阶段中途分出一个支线任务。它带来的好处是可移植性。
• Subagent：将一个范围严格限定的任务交给独立窗口处理，并取回报告。
• /compact 压缩当前上下文，并以此为种子开启一个新会话。这是默认选项，位于决策树底部，而不是首选项。

阅读 PHASE-BOUNDARIES.md 查看有序的决策树：五个问题、每个分支背后的理由，以及为什么主要来源的成本使 Continue 成为首先应当排除的选项。在边界处做出决策；阶段中途，则继续当前工作，或将剩余部分拆分给 Subagent。

独立工具

完全脱离主流程。

• /grill-me：与 /grill-with-docs 一样进行不间断访谈，但无状态：不会在本地保存任何内容，也不会创建 GLOSSARY.md。当你不在工作目录中时使用它（例如打磨计划、设计、文稿，或任何没有关联代码仓库的内容）。如果你在工作目录中，则使用 /grill-with-docs：它会进行同样的访谈并留下记录，因此严格来说是更好的选择。
• /grilling 本身就是访谈的基本机制：轮次、前沿问题和事实由 Agent 负责，决策由你负责。/grill-me 和 /grill-with-docs 是两个命名入口，而 /triage、/wayfinder 和 /improve-codebase-architecture 都会在内部运行它。只有在你希望直接进行访谈、不需要任何封装时，才直接使用它。
• /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 secrets，这样你就不必每次都向 Agent 重新解释操作流程。它由模型调用，因此 Agent 一遇到只有你才能克服的障碍，就会使用它。如果 Agent 能自己完成，就应该自己完成；只有确实需要人类参与时才用它。
• /wait-what 用于纠正没有传达清楚的信息。你可以在对话中途、任何其他技能内部使用它，Agent 会结合你缺少的上下文，用通俗英语重新说明刚才的内容，并使用 GLOSSARY.md 中的词汇。它可以事后使用；/grill-with-docs 则是事前的解决办法，因为尽早约定共同语言，才能避免术语一开始就出现。
• /step-by-step（单独安装）适用于你必须亲自点击操作、而且从未操作过的流程：创建 PAT、指向域名、设置 CI 密钥。它会自行完成终端操作，然后给你一个编号步骤块（每个字段都填入字面值，每个链接都是深层 URL，并在陷阱出现的步骤中标明），然后等待你的操作。/wizard 会将值得重复执行的流程封装进 bash 脚本，而这个工具只会带你走一遍流程。当这些步骤对每周都要操作的人来说显而易见、对你来说却不清楚时，就用它。
• /teach：在多个会话中学习一个概念，并将当前目录用作有状态的工作区。
• /writing-for-agents 是编写 Agent 所使用文档的参考资料：技能、AGENTS.md、被其他文档指向的文档。

前置条件

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