issue-writing

编写、创建或更新 GitHub issue,查找重复问题并组织可执行的任务信息。在准备 issue 文案、创建 issue 或关联父子任务时使用。

SKILL.md

GitHub

Issue Writing

让读者理解问题或目标、工作边界和如何判断完成,并使相关工作易于查找与跟踪。

先了解仓库与现有问题

  • 确认目标仓库与任务,读取适用的 AGENTS.md、CONTRIBUTING.md、issue 模板及相关约定。对外部仓库,了解维护者要求和现有 issue 的语言与写法。
  • 创建前搜索目标仓库的开放和已关闭 issue,使用问题、功能、模块及其同义词等多个相关关键词,检查候选的正文、状态和范围,区分真正重复、部分重叠和单纯相关。
  • 已有 issue 完整覆盖且仍适用时优先复用;对已关闭 issue 核实关闭原因与当前问题是否仍相同。部分重叠时说明新问题的独立范围并链接相关 issue。更新或评论已有 issue 前确认操作在本次授权内;无法完成必要查重时说明限制,待查重后再创建。

标题与正文

  • 标题使用英文,简洁说明具体问题或期望结果,遵循仓库已有标题格式,保留产品名称和标识符的原有大小写。
  • 我们自己的仓库正文用中文;外部仓库明确由外国维护者为主时用英文。其他外部仓库根据维护者要求与现有交流语言判断,仍不明确时先询问。若明确要求与仓库规则冲突,说明冲突并确认处理方式。
  • 正文中,中文、英文和数字相邻时必须用空格隔开,例如“使用 GitHub API 2 次”;代码、标识符和链接保持原有写法。
  • 有适用模板时按模板填写;否则围绕背景、目标或问题、范围和可验证的验收条件组织,按实际规模取舍,小问题保持简短,不留空章节。
  • 缺陷说明实际与预期行为、复现步骤或输入、相关版本和影响;功能或任务说明预期结果、必要边界、验收条件及相关依赖。计划、迁移或重构按需说明目标状态、必须保持的行为、阶段与验收、风险和回滚。讨论类问题写清可选方案、取舍及待决定事项。
  • 区分事实、推测和未验证内容;提供可供目标读者访问的关键证据或链接,敏感数据先脱敏。详细日志和产物放在约定的任务记录中,issue 保留理解、执行和验收所需的信息。

父子关系与跟进

  • 属于已有大计划、迁移或重构的工作时,确认正确的父 issue 和子任务范围,将新 issue 建立为真正的 sub-issue。拆分计划时也为拆出的独立任务建立父子关系;不需要独立跟踪的步骤可用正文任务清单。普通链接或任务清单不等同于父子关系。
  • 在 GitHub 使用支持 sub-issue 的界面或工具,例如创建时使用 gh issue create --parent <parent>,或创建后使用 gh issue edit <parent> --add-sub-issue <child>。确认权限和平台限制;创建或关联受阻时保留已有结果并报告原因,不把普通链接当作已完成关联,也不覆盖已有父关系。
  • 创建后回读标题、正文、链接和实际父子关系,确认与意图一致。任务进行中,按约定更新正文中的当前计划与验收条件,并用评论记录重要进展、决策和证据;复杂计划可标注当前状态及日期,方案变化时说明取代关系。更新前先读取当前远端内容,保留他人新增信息。
  • 任务同时有 issue 和 PR 时双向关联:issue 记录背景、进展和验收,PR 说明代码变化及验证结论。完成或关闭时依据实际验收说明完成情况和遗留事项;发布、修改和关闭等操作均按当前任务授权执行。