ask-matt

name	ask-matt
description	询问当前情境适合使用哪个 Skill 或工作流。本 Skill 是仓库内其他 Skills 的路由入口。
disable-model-invocation	true

Ask Matt

你不必记住仓库里的每个 Skill；拿不准时就从这里开始。

工作流（flow） 是穿过多个 Skills 的一条路径。大多数任务沿着一条主流程推进，另有两个**入口流程（on-ramps）**汇入其中。其余 Skills 要么独立使用，要么作为底层词汇体系，为其他流程提供支撑。

主流程：从想法到交付

大多数工作都会沿着这条路线推进：你有一个想法，并希望把它实现出来。

1. /grill-with-docs — 通过访谈打磨想法。已有代码库时从这里开始：它会持续保存状态，把了解到的内容写入 CONTEXT.md 和 ADR。（没有代码库时使用 /grill-me，参见“独立使用”。两者运行同一个 /grilling 基础流程；grill-with-docs 还会留下完整的文档记录。）

2. 分支——所有问题都能通过对话确定吗？ 某个问题需要通过可运行的结果来回答时，例如状态设计、业务逻辑，或必须亲眼比较的 UI，应暂时转入原型流程，并在往返两个方向上使用 /handoff 衔接会话（参见“跨会话协作”）：

   • 先运行 /handoff 导出当前上下文，再基于该文件开启一个新会话；
   • 使用 /prototype 编写一次性代码，回答这个问题；
   • 再运行 /handoff 带回得到的结论，并在最初讨论想法的会话中引用该文件。

3. 分支——这项构建工作是否会跨越多个会话？

   • 是 → 先运行 /to-spec，把当前讨论整理成规格；再运行 /to-tickets，将规格拆成一组示踪弹式工单（tracer-bullet tickets），并由每个工单声明自己的阻塞关系（blocking edges）。使用本地跟踪器时，产物是一份按顺序手动执行的 tickets.md；使用真实的 Issue 跟踪器时，阻塞关系会写成平台原生依赖链接，所有前置阻塞均已完成的工单都可直接领取。针对每个工单分别启动一次 /implement，并在工单之间清空上下文。
   • 否 → 直接在当前上下文窗口中运行 /implement。

   无论选择哪条分支，/implement 都会在内部驱动 /tdd 实现每个 Issue：一次完成一个红—绿切片；随后运行 /code-review 收尾，在提交前从“规范（Standards）”和“规格（Spec）”两个维度审查差异。只需要以测试优先方式实现一个明确行为时，可以单独使用 /tdd。需要以某个固定点为基准审查分支或 PR 时，可以单独使用 /code-review。

上下文卫生

步骤 1 至步骤 3 应始终位于同一个连续的上下文窗口中。在 /to-tickets 完成前，不要压缩或清空上下文，使追问、规格和工单都建立在同一套思考基础上。此后，每次 /implement 都应从全新会话开始，只依据当前工单开展工作。

这条原则受**高效区间（smart zone）**限制：在这个窗口内（对于当前先进模型，大约为 120k tokens），模型仍能保持敏锐推理。如果会话在运行 /to-tickets 前已接近该区间，不要继续依赖已经退化的推理质量；运行 /handoff，然后在新会话中继续。

入口流程

这些起点会生成待办工作，随后汇入主流程。

• 缺陷和需求不断积压 → 使用 /triage。它通过一组分诊角色推动 Issues 流转，最终产出可直接交给 Agent 的 Issues，之后由 /implement 接手。

  分诊只适用于并非由你创建的 Issues，例如缺陷报告、外部提出的功能请求，以及任何未经整理的原始需求。/to-tickets 生成的工单已经可以直接交给 Agent，不得再次对它们运行分诊。

• 某个东西坏了 → 使用 /diagnosing-bugs。它适用于难以直接解决的问题：第一眼无法定位的缺陷、间歇性失败，以及悄然出现在两个已知正常状态之间的回归。该 Skill 会拒绝在建立**紧密反馈闭环（tight feedback loop）**前推测原因；这个闭环必须包含一条已经能让当前缺陷变红的命令。随后，它会完成修复并补充回归测试。复盘发现真正的问题在于缺少可锁定缺陷的良好 seam 时，后续工作会交给 /improve-codebase-architecture。

• 规模巨大且仍处于迷雾中的工作——例如绿地项目或大型功能构建，单个会话无法容纳 → 使用 /wayfinder。当当前位置到目标之间的路线仍不清晰时，它会在 Issue 跟踪器中建立一张由调查工单组成的共享地图，逐项解决这些工单；产出的是决策，而非交付物。随着迷雾逐步消散，路线最终变得清晰。之后从 /to-spec 汇入主流程；如果后来发现工作量足够小，也可以直接进入 /implement。/grill-with-docs 适合在一个会话中能够完整把握的想法，wayfinder 则处理一个会话装不下的工作。

代码库健康

这部分用于日常维护，不属于功能开发。

• /improve-codebase-architecture — 有空时即可运行，用来保持代码库适合 Agent 操作。它会找出一批深化机会（deepening opportunities）；选择其中一项后，就得到一个可以带入主流程、交给 /grill-with-docs 打磨的新想法。这个 Skill 负责勘察和寻找候选项；下文的 /codebase-design 则是设计所选候选项的工作台。

底层词汇体系

下面两个由模型调用的参考 Skill 位于其他流程之下，各自作为相关词汇的唯一事实来源。遇到的问题出在术语和概念而非流程时，可以直接调用它们；上面的 Skills 也会在需要时自行引用。

• /domain-modeling — 打磨项目的领域语言：质疑含糊术语，拆解承载多重含义的词（例如一个 “account” 同时表示三种概念），并将难以逆转的决策记录为 ADR。/grill-with-docs 通过这套主动建模纪律，让 CONTEXT.md 始终保持为清晰的术语表。
• /codebase-design — 提供深模块设计所需的词汇体系，包括 module、interface、depth、seam、adapter、leverage 和 locality，用于设计模块的形态：在清晰的 seam 上，以很小的接口封装大量行为。/tdd 和 /improve-codebase-architecture 都使用这套语言。

跨会话协作

• /handoff — 当一条讨论快要占满上下文，或需要临时分出另一条会话（例如进入 /prototype 会话）时，将当前对话压缩成 Markdown 文件。不要留在原会话中继续；应开启新会话并引用该文件，把上下文带到另一侧。它是上下文窗口之间的双向桥梁。需要一个全新会话，同时又必须保留当前讨论时使用。
• /compact（内置命令）— 留在同一条对话中，由系统总结较早的轮次。只在阶段之间的明确断点使用，并且可以接受丢失原始逐字记录时才使用。不得在一个阶段进行到一半时压缩，否则 Agent 可能失去方向。/handoff 用于分叉，/compact 用于继续当前对话。

独立使用

这些 Skills 完全独立于主流程。

• /grill-me — 运行与 /grill-with-docs 相同的持续追问流程，但适用于没有代码库的情况。它不保存状态：不会在本地写入内容，也不会创建 CONTEXT.md。可用来打磨任何不依附于仓库的计划或设计。
• /prototype — 编写一个小型的一次性程序，回答单个设计问题，例如状态模型是否合理，或 UI 应该呈现什么样子。它从创建之初就应被视为可丢弃代码：保留答案，删除实现。它是主流程第 2 步中的临时绕行路线，也可以在任何难以只靠纸面讨论确定的设计问题上单独使用。
• /research — 将资料阅读工作委托给一个后台 Agent：它依据一手资料调查问题，并在仓库中留下带引用的 Markdown 文件。调查期间可以继续处理其他工作。得到的文件应作为输入带入 /grill-with-docs 主流程；研究为思考提供材料，不能代替思考本身。
• /teach — 使用当前目录作为有状态的学习工作区，跨多个会话学习一个概念。
• /writing-great-skills — 编写和编辑高质量 Skills 的参考指南。

前置条件

/setup-matt-pocock-skills — 第一次运行工程工作流前必须先执行，用来配置其他 Skills 所依赖的 Issue 跟踪器、分诊标签和文档布局。自定义 Issue 跟踪器同样受支持。