writing-issues

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing issues

编写问题工单

REQUIRED BACKGROUND: the

technical-writing

skill (hard rules, truth rules, style).

必备背景知识： 掌握

technical-writing

技能（包含硬性规则、真实性规则、风格规范）。

Overview

概述

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

writing-design-docs

; the issue links the design doc and never inlines it. This skill covers the writing only, not prioritization or workflow advice.

The 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

recording-decisions

), never "looked into it".

Work 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

writing-design-docs

to the acceptance list; "what without how" and "no verifiable output" are the two that kill most tickets.

Gherkin-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.

单一来源：问题工单定义“做什么”和“为什么”；代码库中的计划定义“怎么做”。切勿维护两份实时更新的副本；第二份副本必然会出现偏差。
工单编号仅用于提交记录和计划文档，切勿出现在代码、注释、测试名称或用户可见字符串中。
信任代码，而非工单状态：工单的自我报告状态很快会过时；在基于导入或旧工单开展工作前，需对照代码库验证（搜索相关符号、查看历史记录）。
追加内容，而非重写：进行中的工单若需变更范围，需添加带日期的备注，而非静默修改。完成后发现的后续工作需提交新工单，而非编辑已关闭的工单。
子任务是可评审的粗粒度拆分，而非每个微小步骤；微小步骤需包含在计划中。
估算需标注为估算，并说明其依赖条件。
关闭工单时需记录原因，尤其是“不会修复”和“重复工单”的情况：记录原因可避免相同工单被重复提交。