ask-matt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ask Matt

咨询Matt

You don't remember every skill, so ask.

A flow is a path through the skills. Most paths run along one main flow, and two on-ramps merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.

你无需记住所有技能，直接咨询即可。

流程是指使用各项技能的路径。大多数路径遵循一条主流程，另有两条接入流程可并入主流程。其余均为独立技能，或是支撑所有技能的底层词汇体系。

The main flow: idea → ship

主流程：想法 → 交付

The route most work travels. You have an idea and want it built.

/grill-with-docs
— sharpen the idea by interview. Start here whenever you are working in a working directory: it's stateful, retaining what it learns in
```
CONTEXT.md
```
and ADRs. (No working directory? Use
```
/grill-me
```
— see Standalone. Both run the same
```
/grilling
```
primitive;
```
grill-with-docs
```
is the one that leaves a paper trail, which makes it the better of the two whenever a repo is there to leave it in.)
Branch — can you settle every question in conversation? If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by /handoff
in both directions (a prototype lives in its own directory, which is exactly what
```
/handoff
```
is for — see Phase boundaries):
- /handoff
  out, then open a fresh session against that file,
- /prototype
  to answer the question with throwaway code,
- /handoff
  back what you learned, and reference it from the original idea thread.
Branch — is this a multi-session build?
- Yes → /to-spec
  (turn the thread into a spec), then /to-tickets
  to split it into tracer-bullet tickets, each declaring its blocking edges. On a local tracker that's one file per ticket under
```
.scratch/<feature>/issues/
```
  , worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off /implement
  per ticket, /clear
  ing context between each one. Each ticket is self-contained, so the last one's context is disposable.
- No → /implement
  right here, in the same context window.
Either way, /implement
builds each issue by driving /tdd
internally — one red-green slice at a time — then closes out by running /code-review
, a two-axis review (Standards + Spec) of the diff, before committing. Reach for /tdd
on its own when you just want to build a concrete behaviour test-first without a full spec, and /code-review
on its own whenever you want to review a branch or PR against a fixed point.

这是大多数工作遵循的路径。你有一个想法，想要将其落地实现。

/grill-with-docs
—— 通过访谈打磨想法。当你处于工作目录中时，从此处开始：它是有状态的，会将所获取的信息保留在
```
CONTEXT.md
```
和ADR中。（没有工作目录？使用
```
/grill-me
```
—— 参见“独立技能”部分。两者均基于同一个
```
/grilling
```
基础技能；
```
/grill-with-docs
```
会留下记录，因此只要有仓库可存储记录，它就是更优选择。）
分支场景——能否通过对话解决所有问题？ 如果某个问题需要可运行的答案（状态、业务逻辑、需可视化的UI），则通过原型进行绕行，双向通过**
```
/handoff
```
**衔接（原型存放在独立目录中，这正是
```
/handoff
```
的用途——参见“阶段边界”）：
- 执行**
```
/handoff
```
  **转出，然后针对该文件开启新会话，
- 执行**
```
/prototype
```
  **生成一次性代码来解答问题，
- 执行**
```
/handoff
```
  **转回所获成果，并在原想法线程中引用该成果。
分支场景——这是否是跨多会话的构建任务？
- 是 → 执行**
```
/to-spec
```
  （将线程转换为规格文档），然后执行
```
/to-tickets
```
  将其拆分为追踪型工单，每个工单需声明其阻塞依赖**。在本地追踪器中，每个工单对应
```
.scratch/<feature>/issues/
```
  下的一个文件，需手动优先处理被阻塞的工单；在专业追踪器中，依赖会转为原生阻塞链接，因此所有依赖已完成的工单均可被处理——针对每个工单启动**
```
/implement
```
  ，在每个工单之间执行
```
/clear
```
  **清除上下文。每个工单都是独立的，因此最后一个工单的上下文可被丢弃。
- 否 → 直接在此处执行**
```
/implement
```
  **，无需切换上下文窗口。

无论哪种情况，/implement
都会在内部驱动
/tdd
来构建每个工单——每次完成一个红-绿测试切片——然后在提交前运行
/code-review
，对差异进行双维度审查（标准 + 规格）。当你只想先测试再构建具体行为而无需完整规格时，可单独使用**

/tdd

；当你想要针对固定基准审查分支或PR时，可单独使用

/code-review

**。

Context hygiene

上下文整洁性

Keep steps 1–3 in one unbroken context window — don't compact or clear until after

/to-tickets

— so the grilling, spec, and tickets all build on the same thinking. Each

/implement

then starts fresh, working from the ticket.

The limit on this is the smart zone: the window (~150k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before

/to-tickets

, don't push on degraded —

/compact

at the nearest phase boundary and carry on (see Phase boundaries).

将步骤1-3保持在同一个连续的上下文窗口中——在执行

/to-tickets

前不要压缩或清除上下文——这样访谈、规格文档和工单都能基于同一思路构建。每个

/implement

都会从工单开始，重新初始化上下文。

此方式的限制是**smart zone**：模型仍能清晰推理的上下文窗口（在最先进的模型中约为150k tokens）。如果会话在执行

/to-tickets

前接近该限制，不要在性能下降的情况下继续——在最近的阶段边界执行

/compact

压缩上下文后再继续（参见“阶段边界”）。

On-ramps

接入流程

A starting situation that generates work, then merges onto the main flow.

Bugs and requests piling up → /triage
. It moves issues through triage roles and produces agent-ready issues, which /implement
later picks up.
Triage is only for issues you didn't create — bug reports, incoming feature requests, anything that arrives raw. Tickets that
```
/to-tickets
```
produced are already agent-ready, so don't triage them.
Something's broken → /diagnosing-bugs
. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a tight feedback loop — one command that already goes red on this bug — then fixes with a regression test. Its post-mortem hands off to /improve-codebase-architecture
when the real finding is that there's no good seam to lock the bug down.
A huge, foggy effort — a greenfield project or a huge feature build, too big for one session → /wayfinder
, the most cognitively demanding flow here. When the way from here to the destination isn't visible yet, it charts a shared map of decision tickets on the issue tracker and resolves them one at a time — producing decisions, not deliverables — until the fog is pushed back and the way is clear. Where /grill-with-docs
sharpens an idea you can hold in one session, wayfinder is for the idea you can't — and it's slower and denser, so save it for exactly that, never a well-scoped feature.
When the map clears, it hands off, it doesn't build: merge onto the main flow at /to-spec
, which collapses the map's linked decisions into a buildable plan, then
```
/to-tickets
```
and
```
/implement
```
as usual. Looping the map straight into
```
/implement
```
skips that collapse and throws the linked detail away — go straight to
```
/implement
```
only when the effort turned out genuinely small.

生成工作任务并并入主流程的起始场景。

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
```
。

Codebase health

代码库健康维护

Not feature work — upkeep.

/improve-codebase-architecture
— run whenever you have a spare moment to keep the codebase good for agents to operate in. It surfaces deepening opportunities; picking one generates an idea you can take into the main flow at
```
/grill-with-docs
```
. It's the survey that finds the candidates; /codebase-design
(below) is the bench you design the chosen one on.

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

/improve-codebase-architecture
—— 当你有空闲时间时运行，以保持代码库适合Agent操作。它会挖掘深度优化机会；选择其中一个机会会生成一个想法，你可将其带入主流程的
```
/grill-with-docs
```
环节。它是寻找优化候选的调研工具；下方的**
```
/codebase-design
```
**则是设计所选优化方案的工作台。

Vocabulary underneath

底层词汇体系

Two model-invoked references that run beneath the other skills — each the single source of truth for its vocabulary. Reach for them directly when the words, not the process, are the problem; or let the skills above pull them in.

/domain-modeling
— sharpen the project's domain language: challenge a fuzzy term, resolve an overloaded word ("account" doing three jobs), record a hard-to-reverse decision as an ADR. It's the active discipline
```
/grill-with-docs
```
drives to keep
```
CONTEXT.md
```
a clean glossary.
/codebase-design
— the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's shape: a lot of behaviour behind a small interface at a clean seam.
```
/tdd
```
and
```
/improve-codebase-architecture
```
both speak it.

两个由模型调用的参考工具，运行于其他技能之下——各自是其词汇体系的唯一可信来源。当词汇而非流程成为问题时，可直接使用它们；也可由上方的技能自动调用。

/domain-modeling
—— 打磨项目的领域语言：挑战模糊术语、解决一词多义问题（如“account”同时承担三种职责）、将难以逆转的决策记录为ADR。它是
```
/grill-with-docs
```
用于保持
```
CONTEXT.md
```
为清晰术语表的核心方法。
/codebase-design
—— 用于设计模块形态的深度模块词汇（module、interface、depth、seam、adapter、leverage、locality）：在清晰的代码边界后，用少量接口封装大量行为。
```
/tdd
```
和
```
/improve-codebase-architecture
```
均使用该词汇体系。

Phase boundaries

阶段边界

A phase is a chunk of work inside a session — the grilling, the implementation, the QA. At the boundary between two of them you have five options, and picking between them is the fuzziest decision in this whole map:

Continue — stay put. Costs nothing, loses nothing.
/clear
— empty the window, when nothing here matters to what's next.
/handoff
— write a portable markdown file. Narrow: only for a new harness, a new directory, a colleague, or forking a side task mid-phase. What it buys is portability.
Subagent — send a tightly-scoped task to its own window and get a report back.
/compact
— compress this context and seed a fresh session with it. The default, at the bottom of the tree rather than the first reach.

Read PHASE-BOUNDARIES.md for the ordered tree — the five questions, the reasoning behind each branch, and why the primary-source cost makes Continue the one to rule out first. Make the decision at a boundary; mid-phase, continue or split the rest into subagents.

阶段是指会话中的一段工作——访谈、实现、QA等。在两个阶段的边界处，你有五种选择，而选择哪一种是整个指引中最模糊的决策：

继续 —— 保持当前状态。无成本，无损失。
/clear
—— 清空上下文窗口，当当前内容对后续工作无意义时使用。
/handoff
—— 生成可移植的Markdown文件。适用场景有限：仅用于新环境、新目录、同事协作，或在阶段中途拆分侧任务。它的优势是可移植性。
子Agent —— 将范围明确的任务发送至独立窗口，并获取报告。
/compact
—— 压缩当前上下文，并将其导入新会话。这是默认选项，是最后选择而非首选。

阅读PHASE-BOUNDARIES.md查看决策树——五个问题、每个分支背后的推理，以及为何原始信息成本使得继续成为首先需要排除的选项。请在边界处做出决策；在阶段中途，要么继续，要么将剩余任务拆分为子Agent处理。

Standalone

独立技能

Off the main flow entirely.

/grill-me
— the same relentless interview as
```
/grill-with-docs
```
, but stateless: it saves nothing locally and builds no
```
CONTEXT.md
```
. Reach for it when you are not working in a working directory — sharpening a plan, a design, a piece of writing, anything with no repo under it. If you are in a working directory, use
```
/grill-with-docs
```
instead: it runs the same interview and leaves a paper trail, so it is strictly the better one.
/grilling
— the interview primitive itself: rounds, the frontier, facts are the agent's job and decisions are yours.
```
/grill-me
```
and
```
/grill-with-docs
```
are the two named ways in, and
```
/triage
```
,
```
/wayfinder
```
and
```
/improve-codebase-architecture
```
all run it internally. Reach for it directly only when you want the interview with no wrapper around it.
/resolving-merge-conflicts
— work an in-progress merge or rebase conflict hunk by hunk, resolving by intent traced to each side's primary source rather than by picking lines, then finish the operation. It never runs
```
--abort
```
. Standalone and off every flow: reach for it when you are already mid-conflict.
/prototype
— a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway is a constraint on how the code is written, not a promise to destroy it: the answer folds into the real code, and the prototype itself is kept as a primary source on a
```
prototype/<name>
```
branch out of main, pointed at from the implementation issue. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
/research
— delegate reading legwork to a background agent: it investigates a question against primary sources, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take into the main flow at
```
/grill-with-docs
```
— research feeds the thinking, it doesn't replace it.
/to-questionnaire
— when the thing blocking you isn't in your head or the codebase but in someone else's, this writes them a questionnaire to fill in. It's the inverse of
```
/grill-me
```
: instead of interviewing you about the subject, it interviews you about the send — who it's going to, what you need back — and aims the questions at the gap. What comes back is material for
```
/grill-with-docs
```
or
```
/to-spec
```
.
/wizard
— for the steps only a human can take: provisioning infrastructure, setting up credentials or CI secrets, clicking through an unfamiliar third-party dashboard, running a one-off migration or cutover. It generates an interactive bash script that opens each URL, captures each value, and writes it into
```
.env
```
and GitHub secrets — so the procedure stops being something you re-explain to an agent every time. Model-invoked, so the agent reaches for it the moment it hits a wall only you can pass. If the agent could just do it itself, it should; this is for where a human is genuinely in the loop.
/wait-what
— the corrective for a message that didn't land. Use it mid-conversation, inside any other skill, and the agent re-pitches what it just said with the context you were missing, in plain English, using the
```
CONTEXT.md
```
vocabulary. It works after the fact;
```
/grill-with-docs
```
is the upfront cure, because a shared language agreed early is what stops the jargon arriving at all.
/teach
— learn a concept over multiple sessions, using the current directory as a stateful workspace.
/writing-for-agents
— reference for writing documents agents consume: skills, AGENTS.md, pointed-at docs.

完全独立于主流程之外。

/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>
```
分支中，并在实现工单中引用。它是主流程步骤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、相关指向文档。

Precondition

前置条件

/setup-matt-pocock-skills
— run before your first engineering flow to configure the issue tracker, triage labels, and doc layout the other skills assume. Custom issue trackers also work.

/setup-matt-pocock-skills
—— 在首次执行工程流程前运行，用于配置其他技能所需的问题追踪器、分类标签和文档布局。自定义问题追踪器也可兼容。