/to-spec 技能

它的作用

to-spec 把你刚完成的对话变成 spec，并把结果作为单个 issue 发布到你的 issue 追踪器。

It does not interview you. When you reach for it, the deciding is already done. So it synthesises what is known (from the thread, the codebase, your GLOSSARY.md and ADRs) and does not start a new round of questions. The spec records decisions you already made. It is not a place to make new ones.

何时使用

你通过输入 /to-spec; the agent 不会自动调用它。

当构建对一个智能体来说太大时使用它 会话 and must be split across several. That is the whole trigger:

前置条件

to-spec 把规格说明作为 issue 发布，所以 setup-matt-pocock-skills must first configure a tracker and the triage-label vocabulary for this repo. Either kind of tracker works: a real tracker like GitHub, or local markdown files under .scratch/, which work with no extra setup.

规格说明是决策记录

The spec exists because context windows end. You settled many things while 追问审视: the shape of the solution, the choices you argued through, and what you deliberately refused. All of that is in one conversation that you are about to clear. The spec keeps it.

So the spec does not validate or decide anything. It records what you decided, in your project's own vocabulary, so a fresh session can pick up the work without you explaining it again. If the spec states something you never said, that is a defect.

先接缝，后散文

Before it writes anything, to-spec 勾勒 seams where the feature will be tested, and checks them with you. It prefers existing seams to new ones, and picks the highest seam it can. The ideal number of seams for a change is one.

Other skills use those agreed seams later. tdd works only at seams you agreed in advance. code-review reviews the diff against the spec, so a seam nobody agreed to shows up as a review finding. Both connections go through this document. That is why you should take the seam conversation seriously here, and not leave it for implementation.

常见问题

原来的 /to-prd 去哪了？ It is this skill, renamed in v1.1. "Spec" is now the one term used throughout, and the old to-prd slug no longer works, so reinstall under the new name. The old vocabulary is replaced by the pair spec and tickets. The spec is the destination and the decisions that fix it. The tickets are the steps that get there. If you change direction, delete the unfinished tickets and keep the spec.

为什么规格说明得到 ready-for-agent 标签？我不想让智能体基于它实现。 The label means "no further triage needed": the document is complete enough for an agent to work from. It marks an input, not a work order. But AFK 轮询 ready-for-agent cannot see that difference. They will try to build the whole spec in one run instead of picking up the ticket slices. This is the most-reported problem with the skill. Until it changes, exclude the parent spec explicitly in your AFK agent's prompt, or remove the label after /to-tickets 已经运行过了。

为什么不从审问直接到 /to-tickets 跳过规格说明？ Often you should. The spec is worth its step only on multi-session work. Its value is that the tickets are disposable and the spec is not. Each ticket is sized for one fresh 上下文窗口 and then gets deleted or closed, while the spec stays as the one place that records the reasoning behind them. On a single-session change, that gives you nothing, and you pay for an extra synthesis step where the model can drift. Go from 追问审视 to /implement.

我刚完成一张 wayfinder 地图。我该喂给它什么？ Give it the main map issue, /to-spec #<map_issue>，而不是个别的决策任务。 wayfinder produces decisions spread across a map, not deliverables. to-spec collapses them into one document you can build from. If you loop the map straight into /implement, you lose that step.

规格说明是给我审查的，还是只给智能体的？ Mostly for the agent, and it reads that way: complete, dense, and full of references. Read the seams and the out-of-scope section. In those two places, a wrong decision is cheapest to catch now and most expensive to find later. People do complain about reading the whole thing, and there is no summary mode. But if the spec surprises you, the grilling was too shallow; the spec is not too long.

任务开始后，规格说明是保持冻结，还是让智能体重写它？ Nothing keeps it in sync. In practice it is a snapshot of what you knew at that moment, and it goes out of date the first time implementation teaches you something. Treat it as disposable after the work ships. Your GLOSSARY.md and ADRs are the files meant to last. If you learn something during implementation that should last, put it there, not in an edited spec.

我的工作是重构或模块边界，不是功能。模板合适吗？ Less well, and this is a known limitation. The template relies heavily on user stories, which do not fit architectural work. You end up writing stories nobody asked for around decisions that are really about interfaces and invariants. Use the implementation-decisions and testing-decisions sections instead. Record the lasting architectural decisions as ADRs through grill-with-docs, not in the spec.

它会检查追踪器中相关工作，或引用它尊重的 ADR 吗？ No to both. It reads and follows the ADRs for the area it touches, but it does not link them. It also does not search the tracker for overlapping issues before it writes, so a spec can duplicate work that someone already filed, and nothing warns you. If the area is busy, search the tracker yourself first.

/to-tickets couldn't read my spec: it kept truncating. A tracker issue may not return a very large spec in full, and there is no local copy to use instead. To fix this, do not clear or compact between /to-spec and /to-tickets. Run them in the same window, and /to-tickets never has to fetch the spec again.

做到以下就算成功

• It starts writing instead of asking you a new round of questions.
• It shows you the seams before it writes, and proposes as few as it can.
• It uses your project's nouns, not generic product-management boilerplate.
• You remember making every decision in it. It invented nothing to fill a section.
• The out-of-scope section lists real things. The things you refused are usually the most useful lines on the page.

在流程中的位置

to-spec is a step in the main build chain, but only on the multi-session branch of it:

grill-with-docs → to-spec → to-tickets → implement → code-review → retro

Upstream, grill-with-docs makes the decisions that this skill only records, and a finished wayfinder map joins the chain here. Downstream, to-tickets 把规格说明切成 implement 构建。当你不确定哪个技能或流程合适时， ask-matt 为你指路。