ask-matt

询问 Matt

你记不住所有技能，所以不妨问问。

流程是穿过各项技能的一条路径。大多数路径遵循主流程，有些接入路径会汇入其中。其余的都是独立技能，或是在底层运行的词汇层。

主流程：想法 → 发布

大多数工作都会经过这条路径。你有一个想法，并希望将它实现。

1. /grill-with-docs — 通过访谈打磨想法。只要你正在工作目录中，就从这里开始：它会保留状态，把学到的内容记录到 CONTEXT.md 和 ADR 中。（没有工作目录？使用 /grill-me — 参见“独立技能”。两者运行的是相同的 /grilling 基础流程；grill-with-docs 会在磁盘上留下记录，所以只要有 repo 可以存放记录，它就是更好的选择。）
2. 分支 — 你能在对话中解决所有问题吗？ 如果某个问题需要可执行的答案（状态、业务逻辑，或你需要亲眼查看的 UI），就通过 prototype 绕行，并在两个方向上都用 /handoff 衔接（prototype 位于自己的目录中，而这正是 /handoff 的用途 — 参见“阶段边界”）：
   • 使用 /handoff 转到 prototype，然后针对该文件开启新会话，
   • 使用 /prototype 编写一次性代码来解答问题，
   • 使用 /handoff 带回你的发现，并在原始想法的 thread 中引用。
3. 分支 — 这是一个需要跨多个会话的构建吗？
   • 是 → 使用 /to-spec（将 thread 转换为 spec），然后使用 /to-tickets 将其拆分成 tracer-bullet tickets，每个 ticket 都要声明自己的阻塞依赖。如果使用本地 tracker，则每个 ticket 对应 .scratch/<feature>/issues/ 下的一个文件，并按阻塞项优先的顺序手动处理；如果使用真正的 tracker，这些依赖会转化为原生阻塞链接，因此任何阻塞项已就绪的 ticket 都可以开始处理 — 对每个 ticket 运行 /implement，并在每个 ticket 之间使用 /clear 清空上下文。每个 ticket 都是自包含的，因此上一个 ticket 的上下文可以丢弃。
   • 否 → 直接在这里、同一个上下文窗口中运行 /implement。

无论哪种情况，/implement 都会通过在内部运行 /tdd 来构建每个 ticket — 每次完成一个 red-green slice — 并在提交前运行 /code-review 收尾，针对 diff 从两个维度（标准 + 规格）进行审查。如果你只想以测试优先的方式构建一个具体行为，但不需要完整 spec，就单独使用 /tdd；如果你想根据某个基准审查分支或 PR，就单独使用 /code-review。

上下文管理

步骤 1–3 要在同一个不中断的上下文窗口中完成 — 直到 /to-tickets 之后才压缩或清理 — 这样访谈、spec 和 tickets 就能基于同一套思路逐步构建。

其边界是**智能区**：模型仍能清晰推理的窗口（在最先进的模型中约为 150k 个 tokens）。如果在运行 /to-tickets 之前，会话接近这个上限，就不要勉强在退化状态下继续 — 在最近的阶段边界运行 /compact，然后接着进行（参见“阶段边界”）。

入门路径

一种会产生工作的起始情境，之后会汇入主流程。

• Bug 和请求不断累积 → /triage。让 issue 经历分诊角色，并产出可供 Agent 处理的 issue，之后由 /implement 接手。

  分诊只适用于不是你创建的 issue——bug 报告、收到的功能请求，以及任何未经处理直接送来的内容。/to-tickets 生成的工单已经可以交给 Agent 处理，所以不要对它们进行分诊。

• 有东西坏了 → /diagnosing-bugs。适用于棘手的问题：第一眼看不出的 bug、间歇性故障，或在两个已知正常状态之间悄然混入的回归问题。在获得一个 紧密反馈循环——一个在这个 bug 上已经会显示为 red 的命令——之前，它拒绝提出理论；然后通过回归测试进行修复。当事后分析发现，真正的问题是缺少合适的接缝来固定 bug 时，它会交接给 /improve-codebase-architecture。

• 一项庞大而模糊的工作——一个从零开始的项目，或大到无法在一个会话中完成的大型功能开发 → /wayfinder，这里认知要求最高的工作流。当从当前位置通往目标的路径尚不可见时，它会在 issue 跟踪器中绘制一张包含 决策工单的共享地图，并逐一解决——产出的是决策，而非交付物——直到迷雾散去、路径变得清晰。/grill-with-docs 用于打磨一个能在单次会话中完成的想法，而 wayfinder 面向无法在单次会话中完成的想法——它更慢、内容也更密集，因此只在这种情况下使用，绝不要用于范围明确的功能。

  地图清晰后，它会交接，而不是构建：汇入主流程中的 **/to-spec``**，将地图中相互链接的决策整合成可构建的计划，然后像往常一样使用 /to-tickets和/implement。直接从地图循环进入 /implement会跳过这一整合步骤，并丢弃相互链接的细节；只有当这项工作最终证明确实很小时，才直接进入/implement`。

代码库健康

不是功能开发工作——而是维护。

• /improve-codebase-architecture——只要有空闲时间就运行它，保持代码库适合 Agent 操作。它会揭示深化机会；选中一个机会就会生成一个想法，你可以将它带入 /grill-with-docs 主流程。它负责调查并找出候选项；/codebase-design（下文）则是设计所选方案的工作台。

底层词汇

两项由模型调用的参考技能，运行在其他技能的底层——各自是其词汇的唯一可信来源。当问题在于用词而非流程时，可直接查阅它们；也可以让上面的技能调用它们。

• /domain-modeling——打磨项目的领域语言：质疑含糊的术语，厘清多义词（比如“账户”承担了三种不同的工作），并将难以撤销的决定记录为 ADR。这是 /grill-with-docs 引导的一项主动实践，旨在让 CONTEXT.md 成为一份清晰的术语表。
• /codebase-design——用于设计模块形态的深模块词汇（module、interface、depth、seam、adapter、leverage、locality）：让大量行为隐藏在小型接口之后，并置于干净的接缝之中。/tdd 和 /improve-codebase-architecture 都使用这套语言。

阶段边界

阶段是一个会话中的一段工作——审查、实现、QA。在两个阶段的边界处，你有五种选择，如何选择是整张图中最模糊的决策：

• Continue — 留在当前状态。不花费任何成本，也不会丢失任何内容。
• /clear — 清空窗口，当这里的内容与接下来的工作毫无关系时使用。
• /handoff — 编写一个可移植的 markdown 文件。用途狭窄：仅适用于新的 harness、新的目录、同事，或在阶段进行到一半时分出一项附带任务。它带来的价值是可移植性。
• Subagent — 将一项范围明确的任务交给另一个窗口，并接收一份报告。
• /compact — 压缩当前上下文，并以此启动一个新会话。实际上，这是默认选项，但位于决策树底部，而不是首选。

请阅读 PHASE-BOUNDARIES.md，了解有序决策树——五个问题、每个分支背后的推理，以及为什么 primary-source 成本让 Continue 成为最先排除的选项。请在边界处做决定；阶段进行到一半时，继续当前工作，或将剩余工作拆分给 subagents。

独立工具

完全脱离主流程。

• /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 本身会作为一手资料保存在 prototype/<name> 分支中，位于主分支之外，并从实现 issue 指向该分支。它是主流程第 2 步的岔路，但只要设计问题难以纸上解决，就可以使用它。
• /research — 将繁重的阅读工作委派给一个后台 Agent：它会针对一手资料调查问题，并在仓库中留下带引用的 Markdown 文件。它阅读时，你可以继续工作。它生成的文件是供你通过 /grill-with-docs 带入主流程的材料——研究为思考提供信息，而不是取而代之。
• /to-questionnaire — 当阻碍不在你的脑海或代码库中，而在其他人那里时，它会为对方编写一份问卷。它与 /grill-me 相反：它不是采访你对主题的看法，而是采访你关于问卷的发送——要发给谁、你需要对方提供什么——并针对信息差设计问题。收到的答复可用于 /grill-with-docs 或 /to-spec。
• /wizard — 用于只有人类才能完成的步骤：配置基础设施、设置 CI 凭据或 secrets、在不熟悉的第三方仪表板中点击操作、运行一次性的迁移或切换。它会生成一个交互式 bash 脚本，打开每个 URL、收集每个值，并将其写入 .env 和 GitHub secrets——这样你就不必每次都向 Agent 重新解释操作流程。它由模型调用，因此 Agent 遇到只有你能跨越的障碍时会使用它。如果 Agent 能独自完成，就应该由 Agent 完成；这里处理的是确实需要人类参与的环节。
• /wait-what — 用于纠正对方没听懂的消息。在任何其他 skill 中的对话过程中使用，它会结合缺失的上下文，用浅白的语言重新表达刚才说的内容，并使用 CONTEXT.md 中的词汇。它事后补救；/grill-with-docs 则是提前预防，因为及早约定共同语言，才能避免出现行话。
• /teach — 跨多个会话学习一个概念，并使用当前目录作为有状态的工作区。
• /writing-for-agents — 编写供 Agent 使用的文档的参考资料：skills、AGENTS.md、被引用的文档。

前置条件

/setup-leandrocfe-skills — 在首次运行工程工作流之前执行，以配置其他技能所依赖的问题跟踪器、分类标签和文档布局。自定义问题跟踪器也可使用。