写 Issue/工单时用：让工单脱离作者也能被理解和验收的写…

适用于在跟踪器中编写或完善 epic、story、task、bug、spike 及验收标准，把讨论、评审发现或计划转成工单。

适用场景

解决思路

1. 以 `technical-writing` 技能为前置背景，遵循其硬规则、真实性规则和风格。
2. 核心原则：把 issue 写成「没有你也能存活」：写清结果、包含决定 Done 的验收检查、链接每个决策背后的证据、为每个开放部分指定负责人。
3. 提交前执行 tracker 的 read-first：最多读同一类型的最近两个 issue 并匹配其惯例；如果 tracker 中更少，读现有内容后照常提交。
4. 报告人不可用时，不要阻塞；以命名缺口的方式提交。`technical-writing` 检查点（kind、audience、purpose、non-goals）是应该停下来询问的内容。缺失的内容细节（复现步骤、日志行、先前事件链接）在 issue 内变成明确有人负责的开放项。
5. 用 survives-without-you 测试：每个 issue 回答陌生人会问的四个问题。第一条：什么结果？写完成时世界的状态，不是达成步骤；实现属于 plan。
6. 第二条：什么决定 Done？写具体、可独立测试的验收检查。「Handle errors appropriately」不能决定任何事；「a failed upload shows the retry banner and logs at WARN」可以。
7. 第三条：证据是什么？决策或约束来自证据时，链接来源：repo path、文档、URL。
8. 第四条：开放部分谁负责？禁止没有名字或角色的「仍需调查」；指定一个负责人/角色，或明确标记未分配（unassigned）。
9. 为 tracker 维护一份 issue 类型术语表，每项一行定义并一致使用。
10. 定义 Epic：一项工作体；其描述说明结果并链接设计文档。
11. 定义 Story：有用户可见价值，从用户视角写。
12. 定义 Task：没有用户可见表面的工程工作。
13. 定义 Bug：缺陷，当前行为与预期行为矛盾。
14. 定义 Spike：时间盒调查，其输出是决策，不是代码。
15. Spike 的 Done 是记录下来的决策（见 `recording-decisions`），绝不是「研究过了」。
16. 决策后接工作体有两种形态：先做 spike，决策后提交 epic；或 epic 的第一个验收项是已接受的设计文档。两者都有效；选一种并说明采用哪种。
17. 写 Story/Task 时，把 issue 描述当作 what 和 why 的规格，并按骨架填写：**Problem / Why**：从读者视角写可观察问题，有数字就带数字。
18. **Outcome**：完成时世界的状态；不是步骤。
19. **Acceptance**：列出可独立测试的检查项。
20. **Out of scope**：写明本 issue 故意不覆盖的内容。
21. **Open items**：每项都有命名负责人或角色，或明确写 unassigned。
22. **Sources**：列出支撑上述内容的 repo paths、文档、测量数据。
23. 对验收列表应用 `writing-design-docs` 的五个模糊缺陷：如果验收检查不满足「what without how」或「no verifiable output」，就不可测试。
24. 团队使用 Gherkin 风格 given/when/then 时，可将其作为验收检查格式；无论哪种格式，都适用同一可测试性标准。
25. 用 INVEST（independent、negotiable、valuable、estimable、small、testable）作为 story 的规模检查：未通过 small 或 testable 的 story，在提交前拆分。
26. 写 Bug 报告时症状优先，因为下一个读者是搜索错误而来的，并按骨架填写：**Symptom**：逐字错误字符串或可观察的异常行为，可搜索。
27. **Reproduction**：编号步骤，每步一个动作，从干净状态开始。
28. **Expected**：应该发生什么，并给出说明来源；若没有找到书面来源，明确写「no written source found」，而不是编造引用。
29. **Actual**：实际发生什么。
30. **Environment**：版本、平台、相关配置。
31. **Open items**：每项都有命名负责人或角色，或明确写 unassigned。
32. **Suspected cause**：仅在调查过时填写；标记为假设，绝不当事实陈述。
33. Bug 标题承载症状，不承载诊断：用「duplicate reminders at reminder time」，而不是「race condition in scheduler」，除非原因已验证。
34. One home：issue 拥有 what 和 why；repo 中的 plan 拥有 how。绝不维护两份实时副本。
35. Ticket keys 只存在于 commits 和 planning docs 中，绝不出现在 code、comments、test names 或用户可见字符串中。
36. Trust code, not issue status：自报状态很快过时；基于导入或旧 issue 构建前，对照 repository 验证（grep symbols，检查 history）。
37. Append, do not rewrite：进行中的 issue 的范围变更用有日期的追加说明，不做静默编辑。完成后发现的后续工作新建 issue，绝不编辑已关闭的 issue。
38. Subtasks 用粗粒度、可评审的切片，不是每个微步骤；微步骤留在 plan 中。
39. Estimates 标记为估计，并说明它们依赖什么。
40. Closing an issue 时记录原因，尤其是 won't-fix 和 duplicates。

适用边界 · 注意事项

• 当 issue 需要论证设计或权衡备选方案时，不要用本技能；应使用 `writing-design-docs`，issue 只链接设计文档，绝不内联它。
• 当需要优先级排序或工作流建议时，不要用本技能；它只覆盖写作。
• 若尚未具备 `technical-writing` 所定义的硬规则、真实性规则和风格，先补齐该背景再使用。