Ask Matt

---
name: ask-matt
description: 询问哪个技能或流程适合你的情况。本仓库内技能的路由器。
disable-model-invocation: true
---

# Ask Matt

你不必记住每一个技能，所以来问。

**流程（flow）**是穿过技能的一条路径。大多数路径沿一条**主干流程**行进，两条**入口匝道**汇入其中。其余的都是独立技能，或者是在底层运行的词汇层。

## 主干流程：想法 → 交付

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

1. **`/grill-with-docs`**：通过盘问打磨想法。只要你在**工作目录**里就从这里开始：它是有状态的，会把学到的东西保存在 `GLOSSARY.md` 和 ADR 中。（没有工作目录？用 `/grill-me`，见"独立技能"。两者跑的是同一个 `/grilling` 原语；`grill-with-docs` 是会留下书面痕迹的那个，所以只要有仓库可以留痕迹，它就是更好的选择。）
2. **分支：所有问题都能在对话中解决吗？** 如果某个问题需要一个可运行的答案（状态、业务逻辑、必须亲眼看到的 UI），就绕道原型，由 **`/handoff`** 双向桥接（原型住在自己的目录里，这正是 `/handoff` 的用武之地，见"阶段边界"）：
   - **`/handoff`** 跳出去，然后针对那个文件开一个新会话，
   - **`/prototype`** 用一次性代码回答问题，
   - **`/handoff`** 把你学到的东西带回来，并在原始想法线程中引用它。
3. **分支：这是多会话构建吗？**
   - **是** → **`/to-spec`**（把对话变成 spec），然后 **`/to-tickets`** 把它拆成示踪子弹式 ticket，每个都声明自己的**阻塞边**。接着用两种方式之一推进 ticket：
     - **`/implement`** 逐个 ticket 实现，**每个之间用 `/clear` 清空上下文**。在本地跟踪器上，每个 ticket 是 `.scratch/<feature>/issues/` 下的一个文件，按阻塞优先的顺序人工推进；在真实跟踪器上，阻塞边变成原生阻塞链接，所以任何阻塞项已完成的 ticket 都可以被领取。每个 ticket 自包含，所以上一个的上下文可以丢弃。
     - **`/implement-spec`** 一次性实现整份 spec。它把 ticket 读成一张**任务图**，在可领取的**前沿**上并行运行实施者子代理，把一切落到一条**集成分支**上。当你更想编排整个构建、而不是亲自逐张驱动 ticket 时用它。
   - **否** → 就在同一个上下文窗口里 **`/implement`**。

   无论哪种方式，代码都靠驱动 **`/tdd`**（一次一个红-绿切片）来构建，并以 **`/code-review`** 收尾，对 diff 做双轴审查（标准 + 规格）。`/implement` 对每张 ticket 各跑一遍这两步；`/implement-spec` 的每个实施者各自驱动 `/tdd`，然后在集成分支上跑一次 `/code-review`。只想在没有完整 spec 的情况下测试优先地构建一个具体行为时，单独用 **`/tdd`**；任何时候想对照固定点审查分支或 PR，单独用 **`/code-review`**。

   当工作要以 PR 提交时，**`/pr`** 负责塑造 PR body：能说清变更的最小可视化、证明其可行的 before/after 证据、以及单向门/双向门的判断。它是模型调用的，所以 agent 每次写 PR 都会主动拿起来用。

4. **`/retro`** 闭合这个循环。一次构建之后（尤其是跑偏的那种），它会回顾整个会话，为 agent 的**环境**（而非代码）提出改动建议：导航指针、自动化检查、`/code-review` 执行的编码规范、引导文件、工具。机械性错误变成确定性检查；判断题变成编码规范。下一次构建就从更好的环境开始。

### 上下文卫生

把步骤 1–3 保持在**一个不间断的上下文窗口**里（在 `/to-tickets` 之前不要压缩或清空），这样盘问、spec 和 ticket 都建立在同一个思考之上。之后每次 `/implement` 从 ticket 出发、重新开始。在它所回顾的那次会话里、清空之前运行 `/retro`；清空之后，就把它指向那次会话的日志。

这里的上限是**[智能区](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**：模型仍能敏锐推理的窗口（最先进模型约 150k token）。如果会话在 `/to-tickets` 之前就逼近它，不要在劣化的状态下硬撑：在最近的阶段边界 **`/compact`** 然后继续（见"阶段边界"）。

## 入口匝道

一个会产生工作的起点场景，然后并入主干流程。

- **bug 和请求堆积** → **`/triage`**。它让 issue 走过分类角色，产出 agent 就绪的 issue，之后由 **`/implement`** 接手。

  分类只适用于**不是你创建**的 issue：bug 报告、外来的功能请求、任何以原始形态到达的东西。`/to-tickets` 产出的 ticket 已经是 agent 就绪的，所以**不要分类它们**。

- **有东西坏了** → **`/diagnosing-bugs`**。用于那些难啃的：一眼看不出的 bug、间歇性偶发（flake）、在两个已知正常状态之间悄悄溜进来的回归。在拥有**紧反馈循环**之前它拒绝空谈理论（一条已经能对*这个* bug 变红的命令），然后用回归测试修复。修复完成后，在同一会话中运行 **`/retro`**，追问什么本可以避免这个 bug；如果真正的发现是缺少合适的接缝来锁定它，就由 **`/improve-codebase-architecture`** 处理。

- **一项庞大而模糊的工作：绿地项目或大型功能构建，大到一次会话装不下** → **`/wayfinder`**，这是这里认知负荷最高的流程。当从这里到目的地的路还看不见时，它在 issue 跟踪器上绘制一张由**决策 ticket** 组成的**共享地图**，一次解决一个：产出**决策，而非交付物**，直到迷雾被推后、道路清晰。**`/grill-with-docs`** 打磨的是你能在一次会话里 hold 住的想法，wayfinder 则是为你 hold 不住的想法准备的：它更慢、更密，所以只留给这种情况，绝不要用于范围明确的功能。

  当地图清晰时，**它交接，不构建**：在 **`/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）：在干净的接缝后面，用一个小接口承载大量行为。`/tdd` 和 `/improve-codebase-architecture` 都讲这套语言。

## 阶段边界

**阶段**是会话内的一块工作：盘问、实现、QA。在两个阶段的**边界**上你有五个选项，而在这张地图里，选哪个是最模糊的决定：

- **继续（Continue）**：原地不动。不花任何代价，也不损失任何东西。
- **`/clear`**：清空窗口，当这里没有任何东西与下一步相关时。
- **`/handoff`**：写一个可移植的 markdown 文件。用途窄：只用于**新的环境**、**新的目录**、**同事**，或在**阶段中途**分叉一个子任务。它买到的是可移植性。
- **子代理（Subagent）**：把一个范围严格的任务送进它自己的窗口，拿回一份报告。
- **`/compact`**：压缩当前上下文，用它播种一个新会话。它是**默认项**，位于树的底部而不是最先伸手可及的地方。

读 [PHASE-BOUNDARIES.md](PHASE-BOUNDARIES.md) 了解排序的决策树：五个问题、每条分支背后的理由，以及为什么一手来源的成本让**继续**成为第一个被排除的选项。在**边界**处做决定；阶段中途，要么继续，要么把剩余部分拆成子代理。

## 独立技能

完全脱离主干流程。

- **`/grill-me`**：与 `/grill-with-docs` 同样锲而不舍的盘问，但**无状态**：不向本地保存任何东西，不构建 `GLOSSARY.md`。当你**不在工作目录中**工作时用它：打磨计划、设计、一篇文章，任何底下没有仓库的东西。如果在工作目录里，就用 `/grill-with-docs` 代替：它跑同样的盘问并且留下书面痕迹，所以严格来说更好。
- **`/grilling`**：盘问原语本身：轮次、前沿，事实是 agent 的工作而决策是你的。`/grill-me` 和 `/grill-with-docs` 是两条具名的入口，`/triage`、`/wayfinder` 和 `/improve-codebase-architecture` 都在内部跑它。只有当你想盘问、但不要任何外壳时才直接伸手去拿。
- **`/prototype`**：一个回答某个设计问题的小型一次性程序：这个状态模型感觉对吗，或者这个 UI 应该长什么样。一次性是对代码写法的约束，而不是销毁它的承诺：答案折进真实代码，原型本身作为**一手来源**保留在 main 之外名为 `prototype/<name>` 的分支上，由实现 issue 指向它。它是主干流程第 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` 是事前的解药，因为早早约定共同语言才不会让行话出现。
- **`/teach`**：跨多个会话学习一个概念，把当前目录当作有状态的工作空间。
- **`/writing-for-agents`**：编写 agent 消费的文档的参考：skills、AGENTS.md、被指向的文档。

## 前置条件

**`/setup-matt-pocock-skills`**：在第一次工程流程之前运行，配置其他技能所依赖的 issue 跟踪器、分类标签和文档布局。自定义 issue 跟踪器也可以。