writing-issues

编写问题

必需背景： technical-writing 技能（硬性规则、真实性规则、风格）。

概述

核心原则：**编写问题时，要确保即使没有你，它们也能独立成立。**说明预期结果，加入用于判定是否完成的验收检查，为每项决策链接其依据，并明确每个未完成部分的负责人。

何时调用，何时不调用

编写或编辑跟踪事项、提交 Bug、将工作拆分为多个工单或编写验收标准时，请调用。评估不同方案时，不要调用：需要论证设计的问题应使用 writing-design-docs；问题中链接设计文档，不要直接嵌入其内容。此技能仅涵盖写作，不涉及优先级排序或工作流建议。

跟踪工具适用先读原则：提交前，先阅读最多两个近期的同类型问题，并遵循其惯例。如果跟踪工具中的此类问题较少，就阅读现有内容，然后照常提交。

当报告者无法联系时，列明未解决事项并提交，不要因此阻塞。technical-writing 检查点（类型、受众、目的、非目标）是需要暂停并询问的内容。缺失的内容细节（复现步骤、日志行、以往事故的链接）应作为明确标注负责人的待办事项写入问题。

“没有你也能成立”测试

每个问题都应回答陌生读者会提出的四个问题：

1. 预期结果是什么？ 是工作完成后的世界状态，而不是实现步骤。实现方案应写在计划中。
2. 如何判定完成？ 一个具体且可独立测试的验收检查。“妥善处理错误”无法判定任何结果；“上传失败时会显示重试横幅并以 WARN 级别记录日志”则可以。
3. 依据是什么？ 如果某项决策或约束有证据来源，请链接来源：仓库路径、文档或 URL。
4. 谁负责未完成的部分？ 不带姓名或角色的“仍需调查”属于禁止使用的含糊负责人；请注明负责人，或明确标记为未分配。

问题类型

每个跟踪工具使用一份术语表，每种类型各用一行定义，并始终保持一致：

类型	定义
Epic	一组工作；其描述说明预期结果并链接设计文档
Story	对用户有可见价值的事项，从用户视角撰写
Task	不涉及用户可见界面的工程工作
Bug	缺陷：当前行为与预期行为不符
Spike	有时间限制的调查，产出是决策而非代码

Spike 的完成标准是记录决策（参见 recording-decisions），绝不能是“已调查”。

决策之后还要开展一组工作时，有两种合适的形式：先做 Spike，决策后再提交 Epic；或者先提交 Epic，并将获批的设计文档列为第一个验收项。两种方式都有效；选择一种并说明采用哪种。

Story 和 Task 模板

问题描述是说明做什么及为什么的规范：

**Problem / Why:** [the observable problem, from the reader's seat, with numbers where they exist]

**Outcome:** [the state of the world when done; not the steps]

**Acceptance:**
- [ ] [independently testable check]
- [ ] [another]

**Out of scope:** [what this issue deliberately does not cover]

**Open items:** [each with a named owner or role, or an explicit "unassigned"]

**Sources:** [repo paths, documents, measurements behind the above]

根据 writing-design-docs 中的五种含糊缺陷，检查验收列表：未通过“说明是什么，却没有说明如何实现”或“没有可验证的输出”检查的验收项不可测试。

当团队使用 Gherkin 风格的给定／当／则格式时，可用该格式编写验收检查；无论使用哪种格式，可测试性标准都相同。INVEST（独立、可协商、有价值、可估算、小巧、可测试）可用于检查 Story 的规模：不满足“小巧”或“可测试”的 Story，应先拆分再提交。

Bug 报告模板

先写症状：下一位读者是为了查找错误而来的。

**Symptom:** [verbatim error string or observable misbehavior, searchable]

**Reproduction:** [numbered steps, one action each, from a clean state]

**Expected:** [what should happen, with the source that says so, or an explicit "no written source found" rather than a fabricated reference]
**Actual:** [what happens]

**Environment:** [version, platform, config that matters]

**Open items:** [each with a named owner or role, or an explicit "unassigned"]

**Suspected cause:** [only if investigated; labeled as hypothesis, never stated as fact]

标题应说明症状，而非诊断：“在提醒时间重复发送提醒”，而不是“调度器中的竞争条件”，除非原因已经确认。

规则

• 一个归属地。 Issue 记录做什么和为什么；仓库中的计划记录怎么做。绝不维护两份同时生效的副本。
• 工单键。 只出现在提交和规划文档中，绝不出现在代码、注释、测试名称或面向用户的字符串中。
• 相信代码，不相信 Issue 状态。 自报状态很快就会过时；在基于导入的或旧 Issue 开始工作之前，先对照仓库核实（搜索符号、查看历史）。
• 追加，不重写。 进行中的 Issue 若范围发生变化，应添加注明日期的说明，而不是悄悄修改。完成后发现的后续工作应新建 Issue，绝不修改已关闭的 Issue。
• 子任务。 划分为粗粒度、可评审的部分，而不是每个微小步骤；微小步骤写在计划中。
• 估算。 标明为估算，并说明其依赖条件。
• 关闭 Issue。 记录关闭原因，尤其是不会修复和重复项。