jira-report-comment

Jira 工单评论

生成一条简短的 Jira 评论，说明工单中交付了什么，并将其保存为本地 Markdown 文件。

读者——PM、QA 工程师或架构师——已经打开了工单。每重复描述工单内容的一句话，读者都会跳过；这样的句子出现两句后，他们就会停止阅读整条评论。因此，评论只包含工单中没有的信息：实际交付了什么，以及下游人员现在需要做出哪些不同的处理。

默认情况下，评论是一段摘要。Bug 修复会添加「根本原因」部分。只有当差异内容提供了具体理由时，才添加「验证」和「部署」部分。

步骤 1 — 确定工单键

按以下顺序：用户提供的键；否则，git branch --show-current 中第一个匹配 [A-Z]+-[0-9]+ 的内容；否则，询问用户。

继续之前先确认：「我从你的分支中检测到 CX-4328。使用此工单键吗？」

然后预留输出文件，并在本次会话的其余时间内一直写入同一路径——针对同一工单重新运行此技能时，会更新该文件，而不是另建一个：

mkdir -p docs/jira-reports
touch "docs/jira-reports/$(date +%Y-%m-%d-%H%M%S)-<ISSUE_KEY>.md"

步骤 2 — 获取工单

尝试使用 Atlassian MCP 服务的 getJiraIssue 工具，并提供工单键。如果无法使用，请让用户粘贴标题、描述和验收标准。

阅读标题、描述、类型和状态。这些内容是要排除的材料，而不是写作依据。 将其作为排除清单。

步骤 3 — 收集差异

git log --grep="<ISSUE_KEY>" --format="%H %s" --reverse

如果没有找到任何内容，则添加 --all 重试。如果仍然没有找到，则将分支与其基线比较——依次尝试 main、master，然后是 develop：

git diff $(git merge-base HEAD main)..HEAD --stat
git diff $(git merge-base HEAD main)..HEAD

找到提交后，比较整个范围的差异，以呈现最终结果，而非逐步变更：

git diff <FIRST_COMMIT>^..<LAST_COMMIT> --stat
git diff <FIRST_COMMIT>^..<LAST_COMMIT>

如果第一个提交是仓库的初始提交，则使用 git diff $(git hash-object -t tree /dev/null)..<LAST_COMMIT>。如果没有发现有意义的差异，请说明这一点并停止。

如果文件超过约 50 个，请根据统计摘要选择性地阅读——配置、迁移和测试通常比实现代码更快地揭示变更意图。

步骤 4 — 确定需要哪些部分

阅读 references/output-format.md，了解模板、限制和风格。

根本原因——当工单修复现有问题时添加：描述中提到了行为异常、结果错误、缺陷或回归。工单类型为 Bug 是强烈信号，但不是必要条件；有些 Story 和 Task 也会修复问题。根据差异和提交信息推导原因及修复方式——工单描述的是症状，重复症状会让这一部分失去意义。

验证——满足以下至少一项时添加：

• 差异新增了功能开关，且测试路径取决于其状态
• 差异触发了工单中未提及的副作用（邮件、Webhook、日志、指标）
• 差异新增了由工单未提及的输入值触发的代码路径
• 差异改变了工单未提及的角色或权限级别的行为

部署——满足以下至少一项时添加：

• 差异新增或重命名了环境变量
• 差异新增了功能开关（注明名称及默认值）
• 差异新增了需要人工协调的迁移——数据回填、锁表时间较长的架构变更
• 差异新增了队列、计划任务或 cron 条目
• 差异需要更改其他系统中的配置（CDN、IAM、DNS）

如果没有触发条件，则评论只包含摘要，不添加其他内容。对于大多数功能开发来说，这才是预期结果，并不代表你遗漏了什么。

第 5 步 — 起草、审核、保存

先写摘要，然后只添加触发条件成立的章节。接着审核：

• 删除任何描述常规工作的项目——推送代码、重启服务、清理缓存、运行标准迁移。读者默认这些工作已经完成。
• 删去对工单内容的复述。 对照第 2 步中的工单文本重新阅读，删掉所有呼应工单内容的措辞。
• 绝不描述差异中未体现的更改。

写入第 1 步预留的路径，并确认：“报告已保存到 <path>。”让文件保持未跟踪状态——绝不暂存或提交。如果有 humanize-text 技能，请在呈现报告前用它处理报告。

示例 — 错误修复

BUG-789“用户取消订阅时会收到两封取消邮件”。差异移除了旧版 onCancellation 处理程序的注册，只保留 onSubscriptionCancelled 发送邮件；并添加了单次发送测试。

BUG-789

现在取消订阅时只会发送一封确认邮件。

根本原因

• 部分重构后，有两个处理程序订阅了取消事件，因此两者都会触发。
• 移除了旧版注册，使新版处理程序成为唯一事实来源。

无需 Verify（测试路径已包含在工单的描述中），也无需 Deploy（这是常规代码更改）。

示例 — 包含 Deploy

XYZ-456“向活跃会员发送每周摘要邮件”。差异添加了一个 cron 任务、一个默认关闭的 weekly_digest_enabled 标志，以及一个 DIGEST_SENDER_EMAIL 环境变量。

XYZ-456

现在每周一上午 9 点向活跃会员发送摘要邮件，并跳过过去 7 天内没有活动的账户。

Deploy

• 在启用功能前，在生产环境中设置 DIGEST_SENDER_EMAIL
• 烟雾测试通过后，启用 weekly_digest_enabled
• 首次计划任务将在部署后的第一个星期一运行

触发 Deploy 的条件有三项：环境变量、标志和 cron 条目。不触发 Verify——测试路径与工单描述一致。

出现问题时

• 找不到问题——告知用户该键似乎无效，并请他们检查。
• 没有提交记录——直接说明；建议使用分支名，或在提交消息中采用其他键格式。
• MCP 不可用——请用户手动提供工单背景信息。
• 写入失败——显示错误并检查目录权限。