把粗糙的 bug 报告或 PR 改写成简短…

当你需要把零散笔记、对话、PR 描述或 diff 提炼成维护者一分钟内能看懂的 issue 时使用。

适用场景

解决思路

1. 阅读提供的笔记、对话、issue、PR 描述或 diff；如果是 PR，还要查看 spec、设计文档或 README 的改动，它们往往比描述更能说明意图。
2. 识别具体问题；当来源足够清楚时，说明谁或什么受到了影响。
3. 描述期望行为，但不要规定实现方式。
4. 只保留有助于理解或复现问题的上下文。
5. 如果来源是 PR 或 diff，描述该改动试图解决的问题，而不是它修改的文件或代码。
6. 除非无法确定问题和期望行为，否则立即起草 issue；若无法确定，只问一个简短的澄清问题。
7. 一个问题对应一个 issue；如果来源捆绑了不相关的问题，为最重要的那个起草 issue，把其余问题各列一行，并告诉贡献者把它们拆成单独的 issue 和单独的 PR。
8. 如果来源是新增能力而非修复错误行为，不要把缺失当作 bug 来写；描述用户今天不能做什么，以及该功能的完整用户体验：谁使用、从哪里使用、会看到什么。
9. 不要编造来源不支持的用户影响、复现步骤或确定性；如果来源只显示清理、重构或可能的代码异味，就说没有明确的具体问题，而不是硬造一个 issue——这条规则优先于第 6 步；用两三句话回复：来源显示了什么，以及什么证据能让它值得成为 issue。
10. 如果来源修复的是尚未公开的安全弱点，不要起草描述它的公开 issue；建议改为私下报告给维护者。
11. 使用平实的语言和短句。
12. 除非明确需要更多内容来描述复现步骤或大型功能，否则 issue 保持在 200 词以内。
13. 以行为开头，而不是代码、架构或提议的修复；当不理解症状就无法理解问题时，可以用一句话的平实原因说明。
14. 只有在复现或理解问题所必需时才保留技术细节；让症状说得通的限制和默认值（批量大小、配额、上限）算作必需。
15. 保留有用的证据，例如错误消息、截图、链接和文档引用。
16. 不要提及 AI 撰写或审阅了这个 issue。
17. 避免填充内容、赞美、路线图式语言和穷举的边缘情况。
18. 使用贡献者的确定性程度；不要把猜测写成已确认的 bug，当来源描述的是风险而非观察到的失败时，写“can”或“appears to”。
19. 第一行是 issue 标题——在 GitHub 上提交时，把它放进标题字段，不要在正文中重复；对于缺失的能力，标题写结果（“Flag pages with no structured data”），而不是假 bug（“Audits never mention structured data”）。
20. 当没有有用内容可添加时，省略 **Extra context** 部分；约束和范围说明放在那里，包括当维护者合理担心会受影响时说明哪些不受影响。
21. 按给定格式输出：标题行，然后是 ## TL;DR、## What is happening?、## What should happen?，以及可选的 ## Extra context。
22. TL;DR 用一两句话说明现在发生什么、应该发生什么；What is happening? 用平实语言描述当前行为，有具体例子就附上；What should happen? 描述期望行为而不提议如何构建；Extra context 放可选的复现步骤、错误文本、截图、链接或约束。

适用边界 · 注意事项

• 来源只显示清理、重构或可能的代码异味，没有明确的具体问题。
• 来源修复的是尚未公开的安全弱点——应建议私下报告给维护者。
• 问题和期望行为无法确定——此时只问一个简短的澄清问题，而不是强行起草。