jira-status-writeback

Jira 状态回写

内部共享技能。合并后 Jira 状态更新和修复评论的唯一事实来源。宿主必须在 dependencies 中声明此技能；若缺少则中止，并传入字段映射；不得在此处重复说明两步 API 或状态边界。本技能不负责解析 PAT 文件；会话或 MCP 身份验证遵循 jira-read。

前置条件检查：必须提供 jira-wiki-markup；如果缺少，则中止并打印标准安装提示（npx skills add FuDesign2008/open-skills -g --skill '*' --yes）。

运行时机

仅在 PR/MR 成功合并到目标分支后运行。绝不可在创建 PR 时运行。

SOP

1. 状态转换（转换调用中不添加评论）

   • 调用 jira_get_transitions（或等效工具），选择与开发人员负责的「已修复」状态相当的状态。
   • 调用 jira_transition_issue，不带 comment 参数。
   • 不得转换为关闭、已验证或由 QA 负责的状态。
   • 如果没有匹配的转换：跳过转换，发出警告；如果可以，则继续添加评论。

2. 评论（独立调用，验证标记语法保真度）

   • 加载 jira-wiki-markup，并使用该技能的标准修复评论模板（Wiki 标记语法），根据宿主字段映射编写 body。
   • 如果修复评论的 body 中有任何行以 h1. 或 h2. 开头，则将这些标题改写为编号的 # *名称* 项目，使评论保持使用 h3./h4. 和列表。
   • 使用可用的评论工具，通过 body 字段提交文本。绝不要依赖 jira_transition_issue 的 comment 参数来记录修复（它可能会被静默丢弃）。
   • 声明完成前验证保真度：从工具响应（或后续读取）中读回已存储的 body，并与编写的文本进行比较——行首标题（h3./h4.）、*粗体*、{{等宽字体}} 和 [标签|url] 都必须原样保留。仅有 2xx 响应并不代表成功：中间层可能会转义标记语法（将 *粗体* 存储为 \*粗体\*），或改写标题（将 h3. X 改为 ### X），但仍返回 2xx。
   • 如果任何保真度检查失败，则使用捆绑的 REST 后备脚本 scripts/update-comment-wiki.mjs 重写评论（凭据链与 jira-read 相同；创建时不传评论 ID，更新时传评论 ID；脚本会自行重新验证保真度），然后根据其 PASS 输出报告结果。

3. 失败处理

   • 状态转换或评论 API 调用失败 → 发出警告并记录在宿主报告中；不得阻止或回滚已完成的合并。

宿主字段映射

宿主必须为以下语义字段提供具体值（仅在确实不适用时才省略字段，并说明原因）：

字段	含义
修复分支	源分支名称
提交	已合并的 tip SHA 或主要修复提交
PR/MR URL	合并请求 URL
根本原因	简短的根本原因摘要
修复摘要	变更内容
变更文件	关键路径
验证	功能／边界／回归说明（宿主可要求每类至少 ≥2 项）
其他	宿主特定内容：分析报告路径（jira-fix-workflow）、OpenSpec 变更路径（opsx-jira-fix-workflow）、QA 风险等

集成

• 在 frontmatter dependencies 中声明 jira-status-writeback。
• 执行回写时：加载此技能，传入字段映射，并遵循 SOP。
• 宿主中只保留：回写在阶段顺序中的执行时机（合并后；如有要求，则归档后），以及字段映射。