publish-issues

发布 Issue

把眼前的内容——这段对话、规范，或用户刚刚描述的想法——转化为仓库 Issue 跟踪器上的一组示踪弹 Issue，每个 Issue 都声明阻塞它的 Issue。这是 triage 的入站队列对应的出站流程。

阅读 docs/agents/issue-tracker.md 中的跟踪器操作说明，以及 docs/agents/triage-labels.md 中的标签字符串。如果缺少其中任一文件，请说明并建议使用 configure-repo；与此同时，你仍可将草稿写入本地 .scratch/ 文件，但远程跟踪器需要配置。

你发布的每个 Issue，其正文都必须以这一行原样开头：

> *This issue was drafted by AI with `publish-issues`.*

这一行也是 triage 用于跳过这些 Issue 的标记——它们创建时就已准备好交给 Agent，因此再次进行分诊只会把较弱的规范叠加到一份真正的规范上。

流程定位

起草前选择合适的技能；不要重复使用更重量级的技能。

你要处理的内容	使用	不要使用
将对话、想法或规范整理成可领取的工作	publish-issues（本技能）	—
需要可追溯 requirements.md → design.md → tasks.md 的二级功能	plan-tasks（默认发布一个功能 Issue）	publish-issues
需要评估原始入站 Issue 或外部 PR	/triage——由用户调用；告知用户运行该命令	publish-issues

如果用户已经完成完整的规范三件套，plan-tasks 会发布一个功能 Issue，并附上合并后的 Requirements covered:；不要在此处重复创建计划任务。publish-issues 用于从未经过规范三件套流程的工作。

流程

1. 收集上下文

根据对话中已有的信息开展工作。如果用户提供了引用——规范路径、Issue 编号或 URL——请先阅读其完整正文和评论。完成标准： 已完整阅读用户提供的每一项引用，并将要提交的范围写成明确的纳入/排除清单。

2. 探索代码库

如果尚未探索代码，请先熟悉代码，确保标题和描述使用项目的领域词汇表（CONTEXT.md），并遵循涉及部分的 ADR。寻找能让后续工作更容易的预重构——“先让修改变容易，再轻松地完成修改”；预重构应作为第一个独立 Issue。完成标准： 每个切片标题中的领域名词都出现在 CONTEXT.md 中，并且预重构要么作为第一个切片提交，要么明确说明为何不需要。

3. 起草垂直切片

将工作拆分为示踪弹 Issue。

• 每个切片都应贯穿各层（模式、API、UI、测试），形成一条范围狭窄但完整的路径——采用垂直切片，而不是只覆盖单一层的水平切片。
• 每个完成的切片都能独立演示或验证。
• 每个切片的规模都应适合在一个全新的上下文窗口中完成。
• 任何预重构都应排在最前面。

为每个切片标明其阻塞关系——即必须先完成、它才能开始的其他切片。没有阻塞项的切片可以立即开始。

大范围重构是例外。 大范围重构是指会波及整个代码库的一项机械性修改——例如重命名列或重新定义共享符号类型——单次编辑就可能导致成千上万个调用点同时失效，且无法通过任何一个垂直切片实现绿色通过。应按扩展 → 迁移 → 收缩的顺序进行：首先在旧形式旁边添加新形式（不破坏现有功能）；然后按影响范围分批迁移调用点（每个包或目录为一批），每批对应一个被扩展阶段阻塞的 Issue；由于旧形式仍然存在，CI 应在每批迁移后保持绿色；最后在一个被所有迁移批次阻塞的 Issue 中删除旧形式。如果即使分批也无法让每批单独保持绿色，就让这些批次共用一个集成分支，并让它们都阻塞最终的集成与验证 Issue——只有在该 Issue 中才保证绿色通过。

完成标准： 每个切片都是垂直切片（或有充分理由的大范围重构批次），并标明其阻塞关系。

4. 向用户确认

将拆分结果以编号列表呈现。每个切片显示 标题、阻塞项和交付内容（它实现的端到端行为）。然后询问：

• 粒度是否合适——太粗还是太细？
• 阻塞关系是否正确——每个切片是否只依赖真正阻塞它的切片？
• 是否应合并或拆分其中任何切片？

如果某个切片的信息不够明确，且只有用户能做出决定，则必须使用 clarify-decisions 子技能，在发布前一次提出一个问题来厘清。反复迭代，直到用户批准拆分结果。**完成条件：**用户已批准这些切片及其阻塞关系。

5. 发布

按依赖顺序——先发布阻塞项，将已批准的切片发布到配置的跟踪平台，以便每个切片的阻塞关系都能引用真实标识符。无论使用哪个跟踪平台，切片都相同；只有阻塞关系的形式会有所不同。

• 本地文件 → 在 .scratch/<feature-slug>/issues/<NN>-<slug>.md 下为每个切片创建一个文件，按依赖顺序从 01 开始编号，并使用下面的本地模板。绝不将所有切片合并为一个文件。
• 远程跟踪平台（github / gitlab / linear） → 按依赖顺序为每个切片创建一个 issue。若平台支持原生子 issue／阻塞关系，则使用该功能（参见 docs/agents/issue-tracker.md）；否则，在每个 issue 的“阻塞项”中填写阻塞 issue 的标识符。

只为可立即领取的任务添加标签。 ready-for-agent（其映射值见 docs/agents/triage-labels.md）表示自主 Agent 现在就可以领取该 issue——因此绝不能将它加到阻塞项仍未关闭的切片上，否则 Agent 会领取无法完成的工作。是否添加该标签，取决于阻塞关系是否受到强制执行，这是跟踪平台的可观察属性：

• 阻塞关系受到强制执行——跟踪平台会自行阻止被阻塞的 issue（原生依赖关系、Linear 的 blocks 关系）。为每个切片添加 ready-for-agent 标签；阻塞关系会限制被阻塞的切片。
• 阻塞关系仅以文本表示——“阻塞项”只是正文中的一行，没有任何机制强制执行（GitHub Issues、本地文件）。只为前沿切片（没有未关闭阻塞项的切片）添加 ready-for-agent；被阻塞的切片只添加其类别标签，并告知用户在其阻塞项关闭后为每个切片添加该标签。如果完全没有标签机制（本地 .scratch/ 文件），则由模板中的“状态”字段表示相同的两种状态：前沿切片标记为 ready-for-agent，被阻塞的切片标记为 blocked。

处理前沿：发布所有阻塞项均已发布的切片，并按上述规则添加标签。对于纯线性链，按从上到下的顺序发布。不要关闭或修改任何父 issue。 **完成条件：**所有已批准的切片都已在跟踪平台上创建并关联好阻塞关系，且只有可立即领取的切片带有 ready-for-agent 标签。

—

此 issue 由 AI 使用 publish-issues 起草。

**构建内容：**从用户角度描述此切片实现的端到端行为，而不是逐层罗列实现步骤。

**阻塞项：**阻塞此切片的编号／标题，或“无——可立即开始”。

**状态：**按上述标签规则填写。

• 验收标准 1
• 验收标准 2

此 issue 由 AI 使用 publish-issues 起草。

构建内容

从用户角度描述此切片实现的端到端行为，而不是逐层罗列实现步骤。

验收标准

• 标准 1——可独立验证
• 标准 2

阻塞项

• 每个阻塞 issue 的标识符，或“无——可立即开始”。

## 父项

源问题的标识符（如果这是从现有问题创建的）；否则省略。

无论采用哪种形式，都要描述行为和接口，绝不提文件路径或行号——这些信息很快就会过时。例外：如果一次 run-spike 产出了比文字描述更精确地限定决策的代码片段（状态机、归约器、架构或类型结构），则将体现决策的部分内联，并注明其来自 run-spike。如果相关工作已由现有规范涵盖，请在相关验收标准中引用需求 ID（CODE-N.M），以保留追踪关系。

收尾

告知用户当前的工作边界——哪些切片可以立即开始。指引他们进入下一步：使用 execute 系列（build-in-waves / build-by-story / build-inline）或独立的 test-first 逐个处理切片，并在切片之间清理上下文。