to-tickets

转为工单

将计划／规格／对话拆分为工单——追踪弹丸式的垂直切片，每个工单都声明阻塞它的工单。按照各使用方代码仓库的跟踪约定（AGENTS.md）发布。

可复现性不变量

按依赖顺序重放完整的问题集——无论是功能还是 Bug 修复——都必须构建出大致相同的应用，无论由谁或什么来实现。

问题流 = 可构建的规格。以下每条规则都是为此服务。

自包含性

每项影响结果的决策都必须写在工单本身中，或写在工单引用的持久文档中——ADR（writing-adrs）、术语表条目（docs/glossary/）。绝不能依赖对话上下文、约定俗成的知识或实现者自行决定。

**试金石：**两个独立实现者可能构建出实质不同的内容 → 工单规格不足。将决策补充到工单中，或记录为 ADR／术语表条目并附上引用。

新词汇

引入领域概念的工单必须在 ## Introduces 下声明该概念——每行一个 slug，并将每个 slug 链接到仿佛术语文件已存在的位置（docs/glossary/<slug>.md，按“仿佛文件已存在”的约定创建链接）。实现时创建该文件；在此之前，--lint 会报告损坏的交叉引用——这正是强制执行机制，并非 Bug。该列表是工单新增词汇的持久记录。

Bug 修复 = 规格更正

绝不要只写指令（“将文件 Z 中的 Y 改为 X”）。应说明对规格流的更正：

• 工单 N 暗示了 X；实现却做了 Y；X 才是正确的。——或
• 工单 N 指定了 Y；Y 有误；现在正确的是 X′。

重放后会直接构建出 X，而不是先构建 Bug 再打补丁。Bug 修复揭示了规格层面的决策 → 创建 ADR，并在工单中引用。

完成时对齐

工单只有在反映实际构建结果后才算完成。关闭前：将偏差、会话中途调整的范围和决策补回工单（或其 ADR／术语表引用）中。否则，重放得到的会是初稿，而非最终状态。documenting-decisions 的任务后步骤会执行此操作。

深入追问关卡

工单承载重要决策。上下文中没有深入追问会话（docs/glossary/grilling-session.md）→ 停下并询问用户：“未找到深入追问会话——真的要跳过吗？”只有在用户明确确认后才继续；在父工单／PR 中注明跳过。

流程

1. 收集上下文

基于对话上下文开展工作。用户提供了参考资料（规格路径、问题编号／URL）→ 获取资料并阅读完整正文和评论。

2. 探查代码库（可选）

了解当前代码状态。标题／描述使用术语表中的词汇（uvx disambiguate <term>）；遵循所触及区域的 ADR。

寻找预重构机会。“让改动变得容易，然后再进行容易的改动。”

3. 起草垂直切片

将工作拆分为追踪弹丸式工单：

• 每个切片：以狭窄但完整的路径贯穿每一层（架构、API、UI、测试）——垂直切片，而不是只覆盖单一层的水平切片
• 完成的切片可单独演示／验证
• 工作量适合一个全新的上下文窗口
• 先做预重构

对每份草稿应用试金石：将起草过程中的决策（接口、命名、排序权衡）写入工单正文、ADR 或术语表条目——按照 documenting-decisions 逐项标注。

大型重构：垂直切片的例外。 一项机械性改动（重命名列、重新定义共享符号类型）的影响范围横跨整个代码库——一次编辑就会破坏数千处调用点，因此没有任何切片能通过构建。按扩展—收缩顺序处理。扩展：在旧形式旁新增形式，不破坏现有内容。迁移：按影响范围（每个包／目录）分批迁移调用点，每批对应一个依赖扩展步骤的独立工单——CI 保持绿色，旧形式继续存在。收缩：所有调用方迁移完后删除旧形式，该工单依赖每个批次。若各批次无法单独保持绿色 → 维持顺序，共用集成分支，并让所有工单都依赖最后的集成与验证工单——只有在那里才承诺绿色。

4. 请用户确认

编号列表。每个工单包含：

• 标题：简短名称
• 阻塞项：前置工单（如有）
• 交付内容：实现可端到端运行的行为

询问：

• 粒度是否合适？（太粗或太细）
• 阻塞关系是否正确——是否仅包含真正的门槛？
• 是否需要合并或拆分？
• 是否有工单未通过试金石——决策仍只存在于对话中？

反复迭代，直到获批。

5. 发布

按依赖顺序（先处理阻塞项），每个工单创建一个议题 → 关联关系引用真实议题编号。如果任务跟踪器支持原生阻塞关系，则使用该关系；否则添加“Blocked by”部分。除非另有指示，否则应用 ready-for-agent 标签——确保工单从设计上即可由 Agent 领取。

处理前沿：所有阻塞项均已完成的工单。线性链 → 从上到下处理。

请勿关闭或修改父议题。

工单模板：

## Parent

Reference to parent issue (omit if source wasn't an issue).

## What to build

End-to-end behaviour, user's perspective — not layer-by-layer implementation.

## Decisions

Every outcome-shaping decision, stated or referenced (ADR/glossary). Bugfix: spec-correction statement. Omit only if genuinely none.

## Acceptance criteria

- [ ] Criterion 1
- [ ] Criterion 2

## Introduces

- [slug](docs/glossary/slug.md) — one-line meaning. Omit if no new term.

## Blocked by

- Reference per blocking ticket, or "None — can start immediately".

工单正文：如果可用，使用 writing-prose 技能撰写并检查，突出 ticket——不得牺牲精确性和易懂性。

不要包含文件路径或代码片段——它们很快就会过时。例外：如果原型片段比正文更精确地表达决策（状态机、reducer、架构、类型形状），则可内联，并注明原型来源，只保留决策信息丰富的部分。

每次只处理前沿中的一个工单，并在处理下一个之前清空上下文。