jira-cr

Jira 变更请求（CR）技能

此技能指导 Agent 根据提供的 Jira 工单生成变更请求（CR）摘要，并在用户要求时将其发布为评论。请根据当前任务解析代码仓库和 Jira 站点；此技能可独立安装和使用。

触发方式

由用户调用：/jira-cr — 当用户要求为 Jira 工单创建 CR 摘要时（例如，“为 PROJ-001 创建 CR”“对 [Ticket ID] 运行 jira-cr”），请明确使用此技能。

工作流说明

1. 获取 Jira 工单信息：

   • 按功能发现可用的 Jira 工具：站点发现、工单检索、评论列表和评论创建。工具名称会因 Agent 而异；请使用已配置的对应工具，不要假定 MCP 命名空间或 Shell 工具名称固定不变。
   • 根据用户提供的信息和项目上下文解析目标站点和工单编号。如果仍有多个可能的站点，请先询问，再做选择。
   • 获取工单及现有评论。持续翻阅评论分页，直到找到相关的先前摘要，或检查完所有可用评论。如果访问不完整，请说明这一限制，不要声称不存在先前摘要。
   • 从工单中提取 摘要、描述和验收标准（AC）。

2. 检测先前的 CR 摘要：

   • 扫描现有评论，查找之前发布的 CR 摘要——根据其横幅行（首次摘要为“AI-generated CR summary”，更新版为“Updated CR summary”）或任意级别的 Story & CR 标题进行识别。评论正文可能以不同的标记格式返回，因此不要仅依赖字面的 # 前缀。如果有多个匹配项，请使用最新的一条。
   • 记录先前摘要的评论 ID、发布日期、语言，以及任何无法从差异中重新生成的详细信息（例如截图）。

3. 解析并阅读变更范围：

   • 检查代码仓库说明、Git 状态、分支和远程仓库。优先遵循用户明确指定的暂存、提交、分支、MR 或 PR 范围。
   • 对于已暂存的工作，阅读 git diff --cached；对于指定的提交，检查其补丁和父提交；对于提交范围，检查所有指定提交及最终差异；对于分支，验证其基准并比较完整的分支差异；对于 MR/PR，在获取相关引用后，阅读已验证的源/目标引用及完整差异。
   • 如果未指定范围，请根据当前任务、匹配的工单分支以及现有 MR/PR 推断。暂存差异为空，并不能证明缺少实现。如果多个可能的范围会产生不同摘要，请提出一个明确的问题。
   • 阅读相关的上下文代码、调用方和测试，以理解行为。不要仅为生成此摘要而暂存或提交文件。排除无关变更和敏感值。
   • 记录代码仓库、范围模式、适用情况下的基准/头部 SHA，以及变更文件数量。暂存工作没有新的提交 SHA；请标明这是暂存快照及当前 HEAD，不要暗示它已提交。

4. 分析并比较：

   • 根据 Jira 工单中定义的验收标准，对比所选代码变更。
   • 将每项验收标准对应到证据和状态：已实现且已验证、已实现但未验证、部分实现、检查范围内未实现或未知。区分缺少变更与周边代码中已存在的功能。
   • 保留先前验收标准状态／历史记录作为历史证据；说明状态变更，不要悄然替换原状态。
   • 指出代码库中受影响的区域（配置、模块、功能、组件），并像团队模板示例那样使用产品术语描述：模块是模块名称（例如 Order），功能是屏幕上的功能名称，组件是屏幕或小组件路径（例如 Worklist > Inpatients widget），配置是配置开关名称及其适用的站点。不要在模板中写文件名和类名。
   • 报告实际运行的检查及其结果，以及未运行的检查。仅检查代码不能证明运行时正确性或完全满足验收要求。
   • 对于 API 工作，在代码支持的范围内描述端点／方法、相关请求字段、授权、处理过程和源数据解析、重复行为、响应状态及范围。明确标注未知的契约。

5. 使用模板进行总结：

   • 保留下面 CR 模板中的标题和表格，不添加其他章节。表格中每行都要填写状态、结果和简要范围。向用户回复时报告相关命令和日志，不要写在评论中：

   # Story & CR
   
   **Summary** - [Brief one-line summary of what was implemented, noting if it fully meets AC.]
   
   **Affected Areas** - [Comma-separated list of major areas impacted]
   
   | Summary                   | Screenshots |
   | :------------------------ | :---------- |
   | 1. [What the change does for this criterion, with status] | [Image or evidence status] |
   | 2. [What the change does for this criterion, with status] | [Image or evidence status] |
   
   | Affected Areas | Descriptions     |
   | :------------- | :--------------- |
   | Configurations | [Details or N/A] |
   | Modules        | [Details or N/A] |
   | Features       | [Details or N/A] |
   | Components     | [Details or N/A] |
   

   • 为各行编号，但不要写 AC1 或 AC2 标签。团队示例会直接描述各项验收标准。
   • **Atlassian 文档格式（ADF）**是发布格式。Markdown 模板定义内容和顺序，而非正文的字面语法。请构建一个 JSON 文档，其中包含 version: 1、type: "doc" 和按顺序排列的 content 节点。
     • 使用 heading 和 paragraph 节点表示各个部分。两个表格都使用 table、tableRow、tableHeader 和 tableCell 节点；摘要表格中每行对应一项带编号的验收标准。
     • 对 1 级标题 Story & CR 同时应用 strong 和 textColor 标记，并使用 #36b37e。
     • 表格单元格内容必须使用有效的 ADF 块节点。请参阅 ADF 文档结构、ADF 表格节点和 ADF textColor 标记。
   • 通过 Atlassian MCP 使用 ADF 发布：使用 contentFormat 接受 adf 的 Atlassian MCP 评论工具（例如 addCommentToJiraIssue）。先检查工具的实时架构，设置 contentFormat: "adf"，并按 commentBody 所要求的格式传入 ADF 文档；如果 commentBody 是字符串，则发送序列化后的 JSON 文档。
     • 不要使用只提供 markdown 或 html 的评论工具（例如 addOrEditJiraIssueComment）发布此摘要。
     • 如果没有可用的 Atlassian MCP 评论工具接受 ADF，则不要发布。请返回 ADF 草稿，并告知用户检查过哪些工具。
   • 面向整个团队编写（开发人员、BA、QA）。读者无需阅读代码，就能理解每一行：
     • 从用户角度描述每一行：用户做什么、看到什么，并使用屏幕名称。说明无法避免的技术术语。
     • 使用摘要所用语言，以通俗语言描述每种状态。泰语请使用 ทำแล้ว ทดสอบผ่าน、ทำแล้ว ทดสอบไม่ผ่าน、ทำแล้ว ยังไม่ได้ทดสอบ、ทำบางส่วน、มีอยู่เดิมก่อนการ์ดนี้ 或 ยังยืนยันไม่ได้。只有实际运行或有人报告检查结果时才能使用已测试状态，并且必须说明结果。补充几字说明测试范围；如果测试由他人执行，还要注明来源，例如 ทดสอบผ่านบน UAT โดย QA (comment 170406)。绝不要只写 ทดสอบแล้ว。阅读代码不算测试。
     • 如果前后截图都存在，请在 Screenshots 单元格中放入一组前后截图。
     • 在 Features 单元格中，添加一行 ควรทดสอบซ้ำ:，列出通过检查调用方确认可能受变更影响的相邻屏幕或功能。如果没有检查调用方，则省略此行。
     • 对于工单未要求的行为，在 Features 单元格中标记 (เพิ่มนอกเกณฑ์)，以便 BA 和 QA 确认。
     • 发布前重新阅读评论，删去填充内容、重复观点和听起来像机器生成的措辞。

6. 起草和发布：

   • 工单上的首个 CR 摘要：在顶部添加简短说明，指出这是根据检查的变更范围生成的 AI CR 摘要。

   • 已有 CR 摘要：新评论必须引用旧摘要，以便读者了解更新历史：

     • 开头使用更新横幅，而非首次摘要说明，例如：> 🔄 Updated CR summary — supersedes the previous summary posted on 2026-08-19 (comment 400128). 尽可能链接到之前的评论：https://<site>.atlassian.net/browse/<TICKET>?focusedCommentId=<commentId>#comment-<commentId>。
     • 不要添加变更部分。直接更新表格。如果之前的摘要与当前代码相矛盾，请在表格中更正，并在横幅行中说明更正内容。
     • 保留之前摘要中仍然有效、且无法从差异中重新生成的信息（例如截图）；如果仍适用，请明确说明，而不要悄然删去。
     • 除非用户要求使用其他语言，否则沿用之前摘要的语言。

   • 语言和截图：首次摘要应使用团队模板示例中的语言（泰语，产品和 UI 名称保留英文），除非用户或仓库说明另有要求。如果有图片，请添加：截图；对于没有界面的变更，则添加测试输出、API 响应或数据库记录的前后对比。无需为每一行都添加图片，但单元格不能留空。需要图片但尚未附上时，写 รอแนบภาพ 并说明要附上的内容，例如 รอแนบภาพ: ผลรัน test。不需要图片时，写 ไม่มีภาพ。沿用之前的图片时，写 ภาพเดิมใน comment <id>。在 Summary 单元格中保留通过或失败结果，且不要为这段文字添加颜色。

   • 先准备完整评论。用户要求总结或审查时，默认只完成本地草稿，除非用户明确要求发布。如果用户已经要求发布，无需再次询问。如果需要发布但尚未获得授权，只需请求批准已完成且可供审核的草稿。

   • 发布前，确认工单并重新阅读相关的先前摘要，避免重复发布或覆盖更新的内容。如果所选变更在分析期间发生变化，请先刷新证据并更新草稿。

   • 保留现有评论；此工作流会创建带链接的后续评论，而不是删除或覆盖历史记录。

   • 使用前面选定的 Atlassian MCP 评论工具，将 ADF 评论发布到已确认的工单。

7. 验证结果：

   • 发布后，获取已创建的评论，并验证其工单、正文和链接。如果写入结果不确定，请先检查现有评论，再重试，以避免重复发布。
   • 返回评论链接和发布状态，或将结果标记为草稿。明确报告检查或测试方面的限制；没有证据时，不要声称已成功发布。