specs-tickets

规格工单

通过规格驱动的生命周期创建并执行工单，或继续处理现有工单。

技能依赖

此技能属于一组旨在协同工作的技能：

• spec-driven — 核心规则和高级文档导航
• specs-setup — 为新项目初始化 specs/
• specs-tickets（此技能）— 在工单生命周期中创建并执行工单
• specs-review — 审查规格的健康状况、一致性和偏差
• specs-finish-ticket — 在关闭前审查已实现的工单

如果项目缺少其中任何技能，请指示用户先安装这些技能：

npx skills add b12consulting/skills --skill <missing_skill>

始终先加载 spec-driven 技能，以了解核心规则。加载方法论参考，了解详细的生命周期和发现项指南。创建文档时加载模板。

前置条件

1. 确认 specs/ 文件夹存在，并包含 Vision.md、PRD.md 和 Architecture/README.md。如果缺少，请提示用户先运行 specs-setup 技能。
2. 阅读 specs/README.md，然后阅读 specs/Vision.md、specs/PRD.md 和 specs/Architecture/README.md，以了解项目背景。
3. 阅读与你的工单相关的架构子文档，例如 specs/Architecture/data-model.md。

---

入口：新建工单还是继续现有工单？

确定用户是想要新建工单，还是继续处理现有工单。

• 如果用户描述的是新工作，转到下面的“新建工单”部分。
• 如果用户提及现有工单，转到下面的“继续工单”部分。
• 如果不明确，请询问用户。

---

新建工单

阶段 0：创建工单

1. 询问用户要完成什么工作。
2. 确定下一个工单编号：扫描 specs/tickets/，找到现有编号中的最大值并加 1。如果没有工单，则从 001 开始。
3. 根据描述提取简短的 slug，使用小写并以连字符分隔单词。
4. 创建工单文件夹和 Spec.md：

specs/tickets/<NNN>-<slug>/Spec.md

使用以下 frontmatter：

---
id: "<NNN>"
title: "<Descriptive title>"
status: research
owner: ""
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

接着添加一段工单摘要和初始规格框架。

然后进入阶段 1：调研。

---

继续工单

1. 确认工单

询问用户要继续哪个工单，或根据对话上下文确认：

• 工单编号，例如 003
• 描述，例如通过扫描工单标题找到“身份验证工单”

如果无法确定，请列出 specs/README.md 中的活动工单，并请用户选择一个。

2. 阅读工单状态

阅读工单的 Spec.md，并记下 frontmatter 中的状态。然后阅读工单文件夹中的所有现有文档，以了解完整背景。

向用户总结当前状态：工单处于哪个阶段、已完成哪些内容，以及接下来要做什么。

3. 检查偏差

将工单文档与以下内容的当前状态进行比较：

• specs/Vision.md 和 specs/PRD.md — 自编写此工单以来，需求或成功预期是否发生变化？
• specs/Architecture/README.md — 架构是否有所演进？
• 代码库 — 自上次处理工单以来，相关代码是否发生变化？

如果发现偏差：

• 向用户报告具体的不一致之处
• 讨论继续之前是否需要更新工单
• 如果规格发生变化，可能需要更新工单的 Spec.md 或 Plan.md
• 如果代码发生变化，可能需要重新验证已完成的检查清单项

4. 解决阻塞项

如果工单状态为 open-questions：

• 向用户展示 Decisions.md 中尚未解决的问题
• 请用户逐项作出决定
• 将决定记录在 Decisions.md 的 Resolved 部分
• 所有问题都得到解答后，更新工单状态

如果工单的 Plan.md 已记录未解决的阻塞项或顺序限制：

• 报告这些阻塞项及其当前状态
• 讨论是等待、绕过还是调整范围

5. 恢复生命周期

根据当前状态，从适当的阶段继续：

当前状态	下一步操作
research	查看 Research.md 中的发现。进入阶段 2：编写规范。
specifying	检查 Spec.md 是否已通过验证。如果是，进入阶段 3：制定计划。如果否，请提交验证。
open-questions	解决问题，然后返回上一阶段。
planned	查看 Plan.md，包括其中的检查清单；确认后开始实施。
in-progress	根据 Plan.md 中的执行检查清单继续。
done	告知用户工单已完成。询问他们是否想重新打开工单或创建后续工单。
archived	告知用户工单已归档。询问他们是否想改为创建新工单。

6. 更新发现

如果恢复工作时发现了长期适用的假设、阻碍、变通方案、后续事项候选项或遗留风险，请创建或更新 Findings.md。内容应经过筛选并长期适用，而非按时间顺序罗列。

---

工单生命周期

生命周期为：研究 → 编写规范 → 制定计划 → 实施 → 完成审查 → 完成。

在规范、计划和收尾检查点都必须由用户验证。

任何参与者（人或 Agent）都可以执行任何阶段。 生命周期定义的是顺序，而非由谁执行。

---

阶段 1：研究

目标：了解问题领域，并收集编写优质规范所需的信息。

1. 调查与工单相关的代码库、现有文档和外部资源。
2. 确定技术限制、现有模式和潜在方案。
3. 如果工单可能影响领域实体或边界载荷，请确定：
   • 涉及的规范领域概念
   • 涉及的规范边界契约
   • 该契约的所有者、生产者和使用者
   • 序列化或持久化格式是否不同于规范的内存中结构
4. 在 Research.md 中记录发现：
   • 目标：我们要了解什么
   • 发现：按主题整理
   • 考虑过的方案及其优缺点
   • 建议
   • 参考资料
5. 在 Spec.md 中将工单状态更新为 research。

对于简单明了的工单，Research.md 是可选的。 如果用户的描述已明确指明方向，可直接进入阶段 2。单行代码的 Bug 修复无需研究，但具有多种潜在方案的新功能通常需要研究。

第 2 阶段：明确规格

目标：明确完成标准。

1. 根据研究结果或用户描述，编写 Spec.md：

   • 用户故事：谁想要什么，以及为什么。为每个故事指定一个优先级（P1、P2、P3……）。每个故事都应可独立测试，并附上一行验证说明。
   • 验收标准：能够证明工作已完成的具体、可测试条件
   • 范围边界：明确纳入范围和排除在范围之外的内容

2. 检查待澄清事项。 最终确定规格前，检查以下类别是否存在歧义：

   • 功能范围和行为
   • 领域和数据模型
   • 交互和 UX 流程
   • 非功能质量属性
   • 集成和外部依赖项
   • 边缘情况和故障处理
   • 约束和权衡
   • 术语一致性

   对于不完整或缺失的类别，判断澄清是否会实质影响实现。如果会，请询问用户。只提出影响最大的几个问题。如果某个缺口更适合留到规划阶段处理，请在内部记录并继续。

3. 如果仍有问题会阻碍规格制定，请创建 Decisions.md：

   • 在 Open 部分列出每个问题及其背景
   • 为每个问题列出选项及其权衡
   • 为每个问题提供建议答案
   • 请用户在继续之前决定所有未解决的问题
   • 将已解决的问题移至 Resolved 部分，并附上决定、日期和理由

4. 自行验证规格。 在向用户展示之前，检查：

   • 规格中没有泄露实现细节
   • 每项需求都可测试且明确无歧义
   • 验收标准可衡量
   • 范围界定清晰
   • 标记为 [NEEDS CLARIFICATION] 的项目不超过 3 项
   • 所有用户故事都标注了优先级，并附有独立测试说明
   • 只有在属于用户可见或产品级契约时，字段级架构细节才出现在规格中；稳定的技术契约定义应放在架构文档或计划中

   如果有任何检查未通过，请先修正规格再展示。

5. 在 Spec.md 中将工单状态更新为 specifying；如果存在待解决问题，则更新为 open-questions。

6. 向用户展示 Spec.md 以供验证。

检查点：在用户验证规格之前，不要进入第 3 阶段。

---

阶段 3：规划

目标：制定实施策略和可执行的检查清单。

1. 根据已确认的规范，编写 Plan.md：

   • 实施方案：高层次的实施策略
   • 关键设计决策：重要选择及其理由
   • 依赖关系和执行顺序：仅列出会实质影响执行的阻塞项或顺序约束
   • 数据模型和契约影响：规范实体、边界契约、序列化差异，以及相关的兼容或切换策略
   • 实施检查清单：按文件列出的具体执行清单
   • 风险和缓解措施：可能出现的问题及其处理方式
   • 验证：证明计划符合规范的检查项

2. 检查是否与架构文档一致。 如果计划需要架构变更：

   • 明确向用户指出
   • 提议在 specs/decisions/ 中编写 ADR
   • 仅在用户批准后更新 specs/Architecture/README.md 和任何受影响的子文档

3. 覆盖范围检查。 在向用户呈现计划之前，确认 Spec.md 和 Plan.md 保持一致：

   • 每项需求至少对应一个检查清单项
   • 每个检查清单项都能追溯到一项需求或设计决策
   • 两个文件中的术语保持一致

   对于影响数据建模或边界契约的工单，还要确认：

   • 每个变更的规范实体或契约都反映在相关架构文档中
   • 每项契约变更都有明确的检查清单项，用于验证生产方和消费方的一致性
   • 必要的兼容或迁移工作已列入 Plan.md

   如果发现缺漏，请在继续之前更新 Plan.md 或 Spec.md。这项检查应轻量进行——对于检查清单项不超过 5 项的极小型工单，可跳过。

4. 在 Spec.md 中将工单状态更新为 planned。

5. 向用户呈现 Plan.md 以供确认。

检查点：在用户确认计划之前，不要继续实施。

---

阶段 4：实施

目标：执行计划。

1. 按顺序完成 Plan.md 中的执行检查清单：

   • 完成每项后将其勾选
   • 如果某项工作表明规范或计划需要更新，请暂停实施
   • 更新相关文档，告知用户；如果变更影响重大，还需获得用户确认

2. 逐步更新 Findings.md：

   • 将会在会话结束后仍有价值的发现记录在此
   • 发现此类内容时立即创建该文件；不要等到工单接近完成才创建
   • 每条发现都必须以明确的处置结果结尾，例如 Addressed here、Follow-up needed 或 Accepted for now

3. 实施过程中的偏离检测：如果实施发现内容与 Vision.md、PRD.md 或架构文档冲突：

   • 立即提醒用户
   • 创建 ADR 来更新规范，或创建后续工单以修复代码
   • 不要在未说明的情况下偏离规范

4. 在 Spec.md 中将工单状态更新为 in-progress。

---

阶段 5：准备完成审查

目标：将工单移交给独立审查，以便在标记为完成之前进行收尾检查。

1. 确认 Spec.md 中的所有验收标准均已满足。
2. 最后检查 Plan.md 和 Findings.md：
   • 确保已完成的检查清单项均已勾选，或明确标记为已被取代
   • 确保 Findings.md 记录了有持久价值的假设、阻碍、后续候选事项、剩余风险和测试缺口，并为其注明明确的处置结果
3. 如果工单影响数据结构，请更新 specs/Architecture/data-model.md，明确说明变更类别：
4. 暂时不要将工单标记为 done。
5. 请用户开启新的对话，并运行 specs-finish-ticket 技能进行独立审查。

通常，在完成审查通过且用户确认关闭工单之前，工单状态会保持为 in-progress。

---

开发过程中处理变更

实现过程中，需求经常会发生变化。发生变化时：

1. 在 Spec.md 中更新新增或变更的需求。
2. 更新 Plan.md，确保方案、顺序和检查清单仍然符合实际情况。
3. 如果变更揭示了值得记录的假设、变通方案、后续候选事项或剩余风险，请更新 Findings.md。
4. 如果变更影响 Vision.md、PRD.md 或架构文档，请创建 ADR。
5. 如果变更改变了规范实体、边界契约或序列化策略，请更新 specs/Architecture/data-model.md 和/或相关架构文档（前提是这些定义属于系统的长期设计）。
6. 如果变更重大，请与用户重新确认。

规范始终是工单的事实来源，而不是代码。请保持两者同步。

扩展指南

• 小型工单，例如错误修复或配置变更：创建工单、编写规范、制定简洁的计划并附上检查清单、实施，然后提交完成审查。跳过研究阶段。
• 中型工单，例如功能或重构：使用所有阶段。研究阶段可以简短。
• 大型工单，例如新系统或重大重新设计：使用所有阶段。如果 Plan.md 的检查清单超过约 15 项，可考虑将工作拆分为多个工单。