ask-matt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ask Matt

你不需要记住每个 skill，所以直接问。

Flow 是穿过 skills 的一条路径。大多数路径沿着一条 main flow 前进，两个 on-ramps 会并入它。其他内容要么是 standalone，要么是在下层运行的 vocabulary layer。

You don't need to remember every skill, so just ask.

Flow is a path through skills. Most paths follow a main flow, with two on-ramps merging into it. Other content is either standalone or a vocabulary layer running underneath.

The main flow: idea -> ship

这是大多数工作的路线：你有一个想法，并希望把它构建出来。

/grill-with-docs
- 通过访谈打磨想法。有 codebase 时从这里开始：它是 stateful 的，会把学到的内容保存在
```
CONTEXT.md
```
和 ADRs 中。（没有 codebase？用
```
/grill-me
```
，见 Standalone。两者都运行同一个
```
/grilling
```
primitive；
```
grill-with-docs
```
是会留下文档痕迹的版本。）
分支 - 能否在对话中解决所有问题？ 如果某个问题需要可运行的答案（state、business logic，或必须亲眼看到的 UI），就通过 prototype 绕行，并用 /handoff
在两个方向桥接（见 Crossing sessions）：
- /handoff
  导出，然后基于该文件打开 fresh session；
- /prototype
  用 throwaway code 回答问题；
- /handoff
  把学到的内容带回来，并在原始 idea thread 中引用它。
分支 - 这是 multi-session build 吗？
- 是 -> /to-prd
  （把 thread 变成 PRD）-> /to-issues
  （把 PRD 拆成可独立领取的 issues）。因为 issues 彼此独立，每个 issue 之间都要清空 context：每个 issue 启动一个 fresh session，把 PRD 和单个 issue 传给 /implement
  。
- 否 -> 在当前 context window 里直接运行 /implement
  。
无论哪种方式，/implement
都会在内部驱动 /tdd
构建每个 issue：一次一个 red-green slice；然后用 /code-review
收尾，对 diff 做 Standards + Spec 双轴 review，再提交。只想 test-first 构建一个具体 behavior 时，单独用 /tdd
；想按固定点 review branch 或 PR 时，单独用 /code-review
。

This is the route for most work: you have an idea and want to build it out.

/grill-with-docs
- Refine ideas through interviews. Start here when there's a codebase: it's stateful and saves what's learned in
```
CONTEXT.md
```
and ADRs. (No codebase? Use
```
/grill-me
```
, see Standalone. Both run the same
```
/grilling
```
primitive;
```
/grill-with-docs
```
is the version that leaves documentation traces.)
Branch - Can all issues be resolved in the conversation? If a problem requires a runnable answer (state, business logic, or UI that must be seen firsthand), detour via prototype and bridge both directions with /handoff
(see Crossing sessions):
- /handoff
  Export, then open a fresh session based on that file;
- /prototype
  Answer the question with throwaway code;
- /handoff
  Bring back what's learned and reference it in the original idea thread.
Branch - Is this a multi-session build?
- Yes -> /to-prd
  (turn the thread into a PRD) -> /to-issues
  (break the PRD into independently assignable issues). Since issues are independent, clear context between each issue: start a fresh session for each issue, pass the PRD and single issue to /implement
  .
- No -> Run /implement
  directly in the current context window.
Either way, /implement
internally drives /tdd
to build each issue: one red-green slice at a time; then wrap up with /code-review
, conducting a dual-axis review of Standards + Spec on the diff before submitting. Use /tdd
alone when you want to build a specific behavior test-first; use /code-review
alone when you want to review a branch or PR at a fixed point.

Context hygiene

Context Hygiene

步骤 1 到

/to-issues

要留在 同一个未中断的 context window 中；不要 compact 或 clear，这样 grilling、PRD 和 issues 才能建立在同一组思考之上。之后每个

/implement

都从 fresh session 开始，只基于对应 issue 工作。

限制来自 smart zone：在该窗口（最新模型大约 120k tokens）内，模型还能保持敏锐推理。如果 session 在

/to-issues

前接近这个区间，不要硬撑降级状态；用

/handoff

，然后在 fresh thread 中继续。

Steps 1 through

/to-issues

must stay in the same uninterrupted context window; do not compact or clear it, so that grilling, PRD, and issues can build on the same set of thinking. Each subsequent

/implement

starts with a fresh session, working only based on the corresponding issue.

The limitation comes from the smart zone: within this window (approximately 120k tokens for the latest models), the model can still maintain sharp reasoning. If the session approaches this limit before

/to-issues

, don't push through with degraded performance; use

/handoff

and continue in a fresh thread.

On-ramps

起点会生成工作，然后并入 main flow。

Bugs 和 requests 堆积 -> /triage
。它通过 triage roles 推进 issues，并产出 agent-ready issues，之后由 /implement
领取。
Triage 只用于 不是你创建的 issues：bug reports、incoming feature requests，以及任何原始进入的内容。
```
/to-issues
```
产出的 issues 已经是 agent-ready，不要再 triage。
Something's broken -> /diagnosing-bugs
。用于难处理的问题：第一眼看不出的 bug、间歇性 flake、夹在两个 known-good states 之间的 regression。它在拥有 tight feedback loop 前拒绝空想，也就是一个已经能在这个 bug 上变红的命令；然后用 regression test 修复。如果复盘发现真正问题是没有好 seam 能锁住 bug，它会把后续交给 /improve-codebase-architecture
。

Starting points generate work and then merge into the main flow.

Bugs and requests are piling up -> /triage
. It advances issues through triage roles and produces agent-ready issues, which are then picked up by /implement
.
Triage is only used for issues not created by you: bug reports, incoming feature requests, and any content that comes in originally. Issues produced by
```
/to-issues
```
are already agent-ready, so don't triage them again.
Something's broken -> /diagnosing-bugs
. For tough problems: bugs not obvious at first glance, intermittent flakes, regressions stuck between two known-good states. It rejects speculation until it has a tight feedback loop, i.e., a command that already turns red for this bug; then fixes it with a regression test. If a retrospective finds the real issue is the lack of a good seam to lock the bug, it hands off follow-up to /improve-codebase-architecture
.

Codebase health

这不是 feature work，而是维护。

/improve-codebase-architecture
- 有空时运行，保持 codebase 适合 agents 操作。它会暴露 deepening opportunities；选择其中一个会生成一个 idea，可以带入 main flow 的
```
/grill-with-docs
```
。它负责找候选项；/codebase-design
（见下文）是你设计已选候选项时使用的工作台。

This is not feature work, but maintenance.

/improve-codebase-architecture
- Run when you have time to keep the codebase suitable for agent operation. It exposes deepening opportunities; choosing one generates an idea that can be brought into
```
/grill-with-docs
```
in the main flow. It is responsible for finding candidates; /codebase-design
(see below) is the workbench you use when designing the selected candidates.

Vocabulary underneath

两个 model-invoked references 在其他 skills 下层运行，分别是自己词汇的 single source of truth。问题在于词语而不是流程时直接用它们；也可以让上面的 skills 自动拉起它们。

/domain-modeling
- 打磨项目的 domain language：挑战模糊术语、解决 overloaded word（例如一个 "account" 承担三件事）、把难以逆转的决策记录为 ADR。它是
```
/grill-with-docs
```
用来保持
```
CONTEXT.md
```
glossary 干净的主动纪律。
/codebase-design
- deep-module vocabulary（module、interface、depth、seam、adapter、leverage、locality），用于设计 module 的 shape：把大量 behavior 放在 clean seam 上的小 interface 后面。
```
/tdd
```
和
```
/improve-codebase-architecture
```
都使用这套语言。

Two model-invoked references run underneath other skills, each being the single source of truth for their own vocabulary. Use them directly when the problem is about words rather than processes; you can also let the above skills pull them up automatically.

/domain-modeling
- Refine the project's domain language: challenge vague terms, resolve overloaded words (e.g., an "account" taking on three roles), and record irreversible decisions as ADRs. It is the active discipline used by
```
/grill-with-docs
```
to keep the
```
CONTEXT.md
```
glossary clean.
/codebase-design
- Deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing the shape of modules: placing large amounts of behavior behind small interfaces on clean seams. Both
```
/tdd
```
and
```
/improve-codebase-architecture
```
use this set of language.

Crossing sessions

/handoff
- 当 thread 快满，或需要分支到另一个 session（例如
```
/prototype
```
session）时，把对话压缩成 markdown 文件。你不会在原地继续，而是 打开新 session 并引用该文件 来带过 context。它是 context windows 之间的桥，两个方向都能用。想要 fresh session 但又要 保留当前对话 时使用。
/compact
（内置）- 留在 同一个对话 中，让早先 turns 被总结。只在阶段之间的明确断点使用；不要在阶段中途 compact，否则 agent 可能迷路。
```
/handoff
```
是分叉；
```
/compact
```
是继续。

/handoff
- When a thread is nearly full, or you need to branch into another session (e.g., a
```
/prototype
```
session), compress the conversation into a markdown file. You won't continue in place; instead, open a new session and reference the file to carry over context. It is a bridge between context windows, usable in both directions. Use it when you want a fresh session but need to retain the current conversation.
/compact
(built-in) - Stay in the same conversation and let earlier turns be summarized. Use only at clear breakpoints between phases; do not compact mid-phase, otherwise the agent may get lost.
```
/handoff
```
is for forking;
```
/compact
```
is for continuing.

Standalone

完全在 main flow 之外。

/grill-me
- 与
```
/grill-with-docs
```
一样的持续访谈，但用于 没有 codebase 的情境。它是 stateless 的：不在本地保存内容，也不构建
```
CONTEXT.md
```
。用它来打磨任何不属于 repo 的计划或设计。
/prototype
- 一个小型 throwaway program，用来回答一个设计问题：这个 state model 感觉对吗，或者这个 UI 应该是什么样。它从第一天起就是 throwaway：保留答案，删除代码。它是 main flow 第 2 步的绕行，但任何难以纸面解决的 design question 都可以直接用它。
/research
- 把阅读工作委托给 background agent：它对照 primary sources 调研问题，然后在 repo 中留下带引用的 Markdown 文件。你可以在它阅读时继续工作。产物应带入
```
/grill-with-docs
```
的 main flow；research 提供思考材料，但不取代思考。
/teach
- 使用当前目录作为 stateful workspace，跨多个 sessions 学习一个概念。
/writing-great-skills
- 编写和编辑 skills 的 reference。

Completely outside the main flow.

/grill-me
- The same continuous interview as
```
/grill-with-docs
```
, but for scenarios without a codebase. It is stateless: it doesn't save content locally or build
```
CONTEXT.md
```
. Use it to refine any plan or design that doesn't belong to a repo.
/prototype
- A small throwaway program used to answer a design question: does this state model feel right, or what should this UI look like? It's throwaway from day one: keep the answer, delete the code. It's a detour in step 2 of the main flow, but any design question that's hard to solve on paper can use it directly.
/research
- Delegate reading work to a background agent: it researches the question against primary sources and leaves a referenced Markdown file in the repo. You can continue working while it reads. The output should be brought into the main flow of
```
/grill-with-docs
```
; research provides thinking materials but does not replace thinking.
/teach
- Use the current directory as a stateful workspace to learn a concept across multiple sessions.
/writing-great-skills
- Reference for writing and editing skills.

Precondition

/setup-matt-pocock-skills
- 第一次运行 engineering flow 前先执行，用来配置其他 skills 所依赖的 issue tracker、triage labels 和 docs layout。自定义 issue trackers 也可以。

/setup-matt-pocock-skills
- Execute this before running the engineering flow for the first time to configure the issue tracker, triage labels, and docs layout that other skills depend on. Custom issue trackers are also supported.