file-issues

记录议题

将眼前的内容——这段对话、规格说明，或用户刚刚描述的想法——转化为仓库跟踪器上的一组示踪弹议题，并在每个议题中声明阻塞它的议题。这是 triage 输入队列的输出对应流程。

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

你发布的每个议题，其正文都必须以以下这一行开头：

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

这一行也是 triage 用来跳过这些议题的标记——它们创建时就已可供 Agent 使用，因此再次进行分诊会在真实规格说明上叠加一份较弱的规格。

适用场景

起草前选择合适的技能；不要重复使用功能更全面的技能。

你要处理的内容	使用	不要使用
要整理成可领取工作的对话／想法／规格说明	file-issues（本技能）	—
需要通过 requirements.md → design.md → tasks.md 追溯的第 2 级功能	write-plan（它会自行发布任务）	file-issues
需要评估的原始输入议题或外部 PR	/triage — 由用户调用；请告诉用户运行它	file-issues

如果用户已经完成完整的规格三件套，write-plan 会发布带有 Requirements covered: 页脚的任务——不要在此处重复创建。file-issues 用于从未经过这套流程的工作。

流程

1. 收集上下文

根据对话中已有的信息开展工作。如果用户提供了参考资料——规格说明路径、议题编号或 URL——请先阅读其完整正文和评论。**完成标准：**已完整阅读用户提供的所有参考资料，并将要登记的范围明确列为包含／不包含清单。

2. 探索代码库

如果尚未探索代码，请先查看代码，确保标题和描述使用项目的领域术语表（CONTEXT.md），并遵循相关区域的 ADR。留意能让后续工作更容易的前置重构——“先让改动变容易，再做容易的改动”；前置重构本身应作为第一个议题。**完成标准：**切片标题中的每个领域名词都出现在 CONTEXT.md 中，并且前置重构已作为第一个切片登记，或已明确说明不需要。

3. 拆分垂直切片

将工作拆分为示踪弹议题。

• 每个切片都要贯穿各层（架构、API、UI、测试），形成范围窄但完整的路径——要做垂直切片，不能只切某一层。
• 每个已完成的切片都应能独立演示或验证。
• 每个切片的规模都应适合在一个全新的上下文窗口中完成。
• 任何前置重构都应排在最前面。

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

大范围重构是例外。 大范围重构是指一项机械性改动——例如重命名列、重新定义共享符号类型——其影响扩散到整个代码库，导致单次编辑就会同时破坏数千个调用点，因此无法通过单个垂直切片以绿色状态合并。应按扩展 → 迁移 → 收缩的顺序执行：首先在旧形式旁边添加新形式（不破坏任何内容）；然后分批迁移调用点，批次规模根据影响范围确定（按包、按目录），每个批次作为一个被扩展阶段阻塞的议题；由于旧形式仍然存在，各批次之间 CI 都应保持绿色；最后在一个被所有迁移批次阻塞的议题中删除旧形式。如果这些批次也无法各自保持绿色，就让它们共用一个集成分支，所有批次都阻塞一个最终的集成与验证议题——只有到那时才能保证绿色。

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

4. 向用户确认

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

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

如果切片的描述不够明确，且只有用户能决定，必须使用 grilling 子技能逐次提问，直到信息明确后再发布。反复迭代，直到用户批准拆分结果。**完成条件：**用户已批准这些切片及其阻塞关系。

5. 发布

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

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

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

• 阻塞关系受强制执行——跟踪器会自动阻止被阻塞的 issue 开始处理（原生依赖链接、Linear blocks 关系）。为每个切片添加 ready-for-agent 标签；阻塞关系会限制被阻塞的切片。
• 阻塞关系只是文本——“Blocked by”只是正文中的一行内容，没有任何强制机制（GitHub Issues、本地文件）。只为前沿切片——没有未关闭阻塞项的切片——添加 ready-for-agent 标签；每个被阻塞的切片只添加其类别标签，并告知用户在其阻塞项关闭后，将该切片提升为可领取状态。如果没有任何标签机制（本地 .scratch/ 文件），则在模板的 Status 字段中使用同样的两种状态：前沿切片标为 ready-for-agent，被阻塞的切片标为 blocked。

按前沿推进：发布所有阻塞项均已发布的切片，并按上述规则添加标签。纯线性依赖链按从上到下的顺序发布。不要关闭或修改任何父 issue。 **完成条件：**跟踪器上已创建所有获批切片并设置好其阻塞关系，且只有可立即领取的切片带有 ready-for-agent 标签。

— <标题>

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

**要构建的内容：**从用户视角描述此切片实现的端到端行为，而非逐层列出实现步骤。

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

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

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

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

要构建的内容

从用户视角描述此切片实现的端到端行为，而非逐层列出实现步骤。

验收标准

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

阻塞项

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

## 上游问题

如果此内容源自已有问题，请填写该问题的标识符；否则省略。

无论采用哪种形式，都要描述行为和接口，绝不提及文件路径或行号——这些内容会过时。例外：如果原型生成的代码片段比文字描述更精确地确定了某项决策（例如状态机、归约器、架构或类型形式），请内联其中能明确决策的部分，并注明它来自原型。如果已有规范涵盖这项工作，请在相关验收标准中引用需求 ID（CODE-N.M），以保留可追溯性。

完成条件

告诉用户目前可以着手哪些部分。指出下一步：使用 execute 系列（execute-plan / execute-story / execute-inline）或独立的 tdd 逐个处理各部分，并在各部分之间清空上下文。