writing-issues
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseWriting issues
编写问题工单
REQUIRED BACKGROUND: the skill (hard rules, truth rules, style).
technical-writing必备背景知识： 掌握技能（包含硬性规则、真实性规则、风格规范）。
technical-writingOverview
概述
An issue is read months later by someone who was not in the conversation, including you. Core principle: write issues so they survive without you. State the outcome, not the implementation; include the acceptance check that decides Done; link the evidence behind every decision.
问题工单会在数月后被未参与过相关讨论的人阅读，包括你自己。核心原则：编写的问题工单要做到“无需你在场也能理解”。明确预期结果，而非实现方案；包含用于判断“完成”的验收标准；为每个决策附上相关依据的链接。
When to invoke, and not
适用与不适用场景
Invoke when writing or editing tracker items, filing a bug, splitting work into tickets, or writing acceptance criteria. Do NOT invoke for weighing alternatives: when an issue needs a design argued, that is ; the issue links the design doc and never inlines it. This skill covers the writing only, not prioritization or workflow advice.
writing-design-docsThe read-first rule here means the tracker: read two recent issues of the same type and match their conventions before filing.
When the reporter is unavailable, file with named gaps rather than blocking: the stop-and-ask rule applies to the checkpoint fields (kind, audience, purpose, non-goals), while missing content details (a repro step, a log line, a prior-incident link) become explicitly owned open items inside the issue.
适用于编写或编辑跟踪项、提交Bug报告、拆分工作为工单，或是编写验收标准的场景。不适用于权衡备选方案：若问题工单需要论证设计方案，应使用技能；问题工单需链接设计文档，而非将其内容内嵌。本技能仅涉及编写规范，不包含优先级排序或工作流建议。
writing-design-docs这里的首要规则是参考跟踪系统：提交工单前，先查看两个同类型的近期工单，匹配其格式规范。
若报告人无法联系，提交工单时需明确标注缺失信息，而非停滞等待：对于检查点字段（类型、受众、目的、非目标）需遵循“停止并询问”规则，而缺失的内容细节（重现步骤、日志行、过往事件链接）则需在工单内明确标记为待处理项并指定负责人。
The survives-without-you test
“无需你在场也能理解”测试
Every issue answers four questions a stranger will ask:
- What outcome? The state of the world when this is done, not the steps to get there. Implementation belongs in the plan; an issue that prescribes the implementation is stale the moment a better approach appears.
- What decides Done? A concrete, independently testable acceptance check. "Handle errors appropriately" decides nothing; "a failed upload shows the retry banner and logs at WARN" does.
- What is the evidence? Where a decision or constraint came from evidence, link the source: a repo path, a document, a URL. A claim with no source is relitigated later.
- Who owns the open parts? "Still needs investigation" without a name or role is a banned vague owner; name one or mark the field explicitly as unassigned.
每个问题工单都需回答陌生人会提出的四个问题：
- 预期结果是什么？ 完成后的状态，而非实现步骤。实现方案属于计划范畴；若问题工单指定了实现方案，一旦出现更优方案，该工单就会过时。
- 如何判断已完成？ 具体、可独立验证的验收标准。“妥善处理错误”无法作为判断依据；“上传失败时显示重试横幅并以WARN级别记录日志”才是合格的标准。
- 依据是什么？ 若决策或约束是基于某些依据制定的，需链接来源：代码库路径、文档、URL等。无来源的主张后续可能会被重新讨论。
- 待处理项的负责人是谁？ 禁止模糊标注“仍需调查”却不指定姓名或角色；需明确指定负责人，或标记该字段为未分配。
Issue types
问题类型
One glossary per tracker, defined in one line each and used consistently:
| Type | Definition |
|---|---|
| Epic | A body of work; its description states the outcome and links the design doc |
| Story | Something with user-visible value, written from the user's seat |
| Task | Engineering work with no user-visible surface |
| Bug | A defect: current behavior contradicts intended behavior |
| Spike | A time-boxed investigation whose output is a decision, not code |
A spike's Done is the decision recorded (see ), never "looked into it".
recording-decisionsWork that is a decision followed by a body of work fits two shapes: a spike first with the epic filed after the decision, or an epic whose first acceptance item is the accepted design doc. Both are valid; pick one and say which.
每个跟踪系统需有一份术语表，每种类型用一句话定义并保持一致使用：
| 类型 | 定义 |
|---|---|
| Epic | 一组工作内容；其描述需明确预期结果并链接设计文档 |
| Story | 具备用户可见价值的工作内容，从用户视角撰写 |
| Task | 无用户可见界面的工程工作 |
| Bug | 缺陷：当前行为与预期行为不符 |
| Spike | 有时间限制的调研工作，输出为决策而非代码 |
Spike的“完成”标志是记录下决策（参考），而非“已调研过”。
recording-decisions若某项工作是先做决策再执行，有两种处理方式：先提交Spike工单，决策完成后再提交Epic工单；或是提交Epic工单，将“已确认的设计文档”作为首个验收项。两种方式均有效，选择其一并明确说明即可。
Story and task skeleton
Story与任务模板
The issue description is the spec for what and why:
markdown
**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]
**Sources:** [repo paths, documents, measurements behind the above]Apply the five completeness checks from to the acceptance list; "what without how" and "no verifiable output" are the two that kill most tickets.
writing-design-docsGherkin-style given/when/then is an accepted format for acceptance checks when the team uses it; the same testability bar applies either way. INVEST (independent, negotiable, valuable, estimable, small, testable) works as a sizing check for stories: a story failing "small" or "testable" splits before it is filed.
问题工单描述是关于“做什么”和“为什么”的规范：
markdown
**问题/原因：** [从读者视角描述可观察到的问题，如有数据请附上]
**预期结果：** [完成后的状态；而非步骤]
**验收标准：**
- [ ] [可独立验证的检查项]
- [ ] [另一项检查项]
**范围外内容：** [本工单明确不涵盖的内容]
**来源：** [上述内容相关的代码库路径、文档、测量数据]对验收列表应用中的五项完整性检查；“只说做什么不说怎么做”和“无可验证输出”是导致多数工单不合格的两个问题。
writing-design-docs若团队使用Gherkin风格的“给定-当-则”格式，也可用于验收标准；无论采用哪种格式，都需满足可测试性要求。INVEST原则（独立、可协商、有价值、可估算、小粒度、可测试）可用于Story的规模检查：若Story不符合“小粒度”或“可测试”要求，需拆分后再提交。
Bug report skeleton
Bug报告模板
Symptom first, because the next reader arrives searching for the error:
markdown
**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]
**Suspected cause:** [only if investigated; labeled as hypothesis, never stated as fact]The title carries the symptom, not the diagnosis: "duplicate reminders at reminder time", not "race condition in scheduler", unless the cause is verified. A wrong diagnosis in the title misroutes every later search.
先描述症状，因为后续读者会通过搜索错误信息找到该工单：
markdown
**症状：** [准确的错误字符串或可观察到的异常行为，便于搜索]
**重现步骤：** [从干净状态开始的编号步骤，每步一个操作]
**预期行为：** [应该发生的情况，附上相关来源，或明确标注“未找到书面来源”而非编造参考]
**实际行为：** [实际发生的情况]
**环境：** [相关的版本、平台、配置]
**疑似原因：** [仅在已调研后填写；标注为假设，而非事实]标题需包含症状而非诊断结果：例如“提醒时间出现重复提醒”，而非“调度器存在竞态条件”，除非原因已被验证。标题中的错误诊断会导致后续所有搜索出现偏差。
Rules
规则
- One home. The issue owns what and why; the plan in the repo owns how. Never maintain two live copies; the second copy is the one that drifts.
- Ticket keys live in commits and planning docs, never in code, comments, test names, or user-facing strings.
- Trust code, not issue status. An issue's self-reported state goes stale fast; before building on an imported or old issue, verify against the repository (grep the symbols, check the history).
- Append, do not rewrite. Scope changes on an in-flight issue are dated appended notes, not silent edits. Follow-up work found after completion is a new issue, never an edit to a closed one.
- Subtasks are coarse reviewable slices, not every micro-step; the micro-steps live in the plan.
- Estimates are labeled as estimates, with what they depend on.
- Closing an issue records the reason, especially for won't-fix and duplicates: the reason is what stops the same ticket being filed again.
- 单一来源：问题工单定义“做什么”和“为什么”；代码库中的计划定义“怎么做”。切勿维护两份实时更新的副本；第二份副本必然会出现偏差。
- 工单编号仅用于提交记录和计划文档，切勿出现在代码、注释、测试名称或用户可见字符串中。
- 信任代码，而非工单状态：工单的自我报告状态很快会过时；在基于导入或旧工单开展工作前，需对照代码库验证（搜索相关符号、查看历史记录）。
- 追加内容，而非重写：进行中的工单若需变更范围，需添加带日期的备注，而非静默修改。完成后发现的后续工作需提交新工单，而非编辑已关闭的工单。
- 子任务是可评审的粗粒度拆分，而非每个微小步骤；微小步骤需包含在计划中。
- 估算需标注为估算，并说明其依赖条件。
- 关闭工单时需记录原因，尤其是“不会修复”和“重复工单”的情况：记录原因可避免相同工单被重复提交。