Reference · User-invoked · Main flow（编排层）

to-spec 速查

把对话冻结成 spec、发到 Issue tracker 的口袋版。完整教学见 Lesson 0009；原文见 SKILL.md、 agents/openai.yaml、 docs 页（aihero.dev/skills-to-spec）。

一句话

不采访，只合成：把当前对话 + 代码库理解写成一份 spec（即 PRD，需求文档），发布到 setup 配好的 Issue tracker，打 ready-for-agent 标签。主链位置：grill-with-docs → to-spec → to-tickets → implement → code-review。

调用与前置

只能人启动：输入 /to-spec。frontmatter disable-model-invocation: true + openai.yaml allow_implicit_invocation: false；AI 不会自己伸手。
前置：/setup-matt-pocock-skills 已跑过——tracker 形态在 docs/agents/issue-tracker.md（GitHub / GitLab / 本地 .scratch/ markdown / 其它自由文本），标签词表在 docs/agents/triage-labels.md。没跑过？SKILL.md 让你先去跑。

何时用 / 何时别用

用	别用（该去哪）
想法已对齐（grill 完、词已定、ADR 已落），且工程跨多个会话——需要一份能脱离对话存活的文档	一个窗口就能干完 → 直接 `/implement`；没对齐 → `/grill-with-docs`；没配 tracker → setup；路都看不见的大雾工程 → `/wayfinder`（出口就在 to-spec）；别人的原始 bug/需求 → `/triage`；只想先测一个小行为 → `/tdd`

口诀：spec 之前必须已经「知道要做什么」，spec 之后必须真的「大到需要文档」。

三步流程卡

探索仓库（只读）：摸清现状；spec 全程用 CONTEXT.md 的领域词；尊重改动区域的 ADR。
画测试接缝草图（不落盘）：规则 = 已有优先于新开 · 尽量高 · 新开也开最高处 · 越少越好、理想一个。画完必须跟你确认——全流程唯一打断点，别挥手放行。
按模板写并发布（落盘）：<spec-template> 七节 → 发到 tracker → 打 ready-for-agent，无需再过 triage。没有草稿确认环节——输入 /to-spec 本身就是发布授权。

spec 模板七节（<spec-template>）

节	装什么	禁装
Problem Statement	用户视角的问题与价值	解法（归下一节）
Solution	用户视角的解法形状，高层	实现细节
User Stories	很长的编号列表；`As an <actor>, I want a <feature>, so that <benefit>`；覆盖各方面	三五条了事
Implementation Decisions	已定决策：模块、接口、技术澄清、架构决策、schema、API 契约、交互	文件路径与代码片段（例外：prototype 的决策片段——状态机/reducer/schema/type shape，注明来源、修剪到只剩决策）
Testing Decisions	好测试定义（只测外部行为）· 测哪些模块 · prior art（库里的同类参照）	逐条测试用例（归 tdd 阶段）
Out of Scope	明确不做的内容，钉死边界	模糊措辞
Further Notes	其它值得带走的补充	—

会改什么（副作用）

写：Issue tracker 上新增一个 Issue（spec 全文）+ ready-for-agent 标签。本地 tracker 形态下是 .scratch/ 里的文件。
只读不写：仓库代码、CONTEXT.md、ADR（后两者的作者是 grill-with-docs / domain-modeling）。
不碰：已有 Issue（只创建，不修改不关闭）。
消耗：当前对话上下文是它的原材料。
自家产物出生即 agent-ready，不要再送进 triage（triage 只管外来件）。

下一步

同一窗口接着 /to-tickets（默认读对话），或日后新窗口把 spec 的 issue 编号/URL 递给它。
之后每张票一个新窗口 /implement（内部驱动 /tdd），收口 /code-review。
发现活儿其实很小 → 跳过后续，直接 /implement。

上下文卫生

grill → to-spec → to-tickets 必须同一个不清空的窗口；每个 implement 才开新窗口。
逼近 smart zone（~120k token）上限别硬撑：/handoff 换线，别让 spec 从塌掉的窗口里写出来。
wayfinder 合流点就在这里：地图决策在 to-spec 坍缩成可施工计划；直接甩给 implement 会丢掉链好的细节。

微调入口（症状 → 改哪里）

症状	改
开始重新采访你	SKILL.md 开头「Do NOT interview the user — just synthesize」
spec 模板腔、无领域词	先补上游 `CONTEXT.md`（domain-modeling）；再查 Process 第 1 步
接缝又多又低 / 不确认	Process 第 2 步四条规则 + 「Check with the user」
User stories 只有三五条	模板 User Stories 节的 LONG / extremely extensive
spec 里出现路径或大段代码	模板 Implementation Decisions 的禁令与 prototype 例外边界
标签错 / 想换字符串	角色决策在 Process 第 3 步；字符串在 `docs/agents/triage-labels.md`
发错 tracker	`docs/agents/issue-tracker.md`（setup 产物），与 SKILL.md 无关
AI 擅自启动	frontmatter + `agents/openai.yaml` 两个开关
想改模板形状	`<spec-template>` 块——模板唯一的家

工作正常的三个信号（docs）

直接动笔写，而不是抛出一轮新问题。
动笔前先给你看接缝，且数量尽量少。
spec 用你项目的领域词，不是通用模板腔。