Jira Bug 修复工作流

端到端 Jira Bug 修复流程，阶段 1～4 只读不写。默认手动模式，阶段间需用户确认。

前提：mcp-atlassian 已配置且 PAT 有效；Git 环境正常。 输出规范：Markdown 结构化（标题/列表/表格/代码块），代码引用用 startLine:endLine:filepath；容易 → 精简，困难/极难 → 详细。 格式参考：各阶段输出模板见 reference.md。

触发词与模式

说法示例	模式	说明
「修复这个 bug [URL]」「帮我修复 [URL]」jira-fix [URL]	👤 手动	默认，方案/计划/提交需用户确认
「自动修复 [URL]」「修复 [URL] 自动模式」jira-fix [URL] --auto	🤖 自动	全流程自动执行，无需确认
「强制修复 [URL]」「跳过分级修复 [URL]」jira-fix [URL] --force	🤖 自动	跳过难度分级，强制自动执行
「继续修复 [URL]」「再次修复 [URL]」jira-fix [URL] --retry	👤 手动	跳过阶段0/1，从阶段2重新分析（修复不完整时使用）
「从上次继续」「恢复修复 [URL]」jira-fix [URL] --resume	当前模式	从断点恢复（中途中断时使用）

模式识别规则：触发词中含「自动」「--auto」→ 自动模式；含「强制」「跳过分级」→ 跳过分级（自动模式）；含「继续修复」「再次修复」「--retry」→ 阶段2重入（修复迭代）；含「从上次继续」「恢复」「--resume」→ 断点恢复；其余默认手动模式。

模式差异速查

阶段	🤖 自动模式	👤 手动模式
阶段0：前置检查	P0 自动拦截，工作区自动 stash	P0 提示，工作区提示用户处理
阶段2.5：难度分级	极难 → 终止，输出标记报告	极难 → 列出风险，用户选择 A/B
阶段3：探索与审查方案	AI 自动探索并循环审查（≤3轮），通过后自动进阶段4；超限暂停（批量模式标记跳过）	输出方案表→用户选择→审查→用户判定通过/不通过→循环至通过后进阶段4
阶段4：制定计划	自动确认，直接进阶段5	等用户确认
阶段5：执行计划	前置创建分支 + 执行 + Linter + 自动生成分析报告	单工程：直接创建分支，无需确认；多工程：展示分支计划后确认创建 + 执行 + Linter
阶段6：提交 PR	自动 push + Jira 状态回写	展示提交计划，用户确认后 AI 执行 push
阶段7：合并 PR/MR 与收尾	CI 通过后自动合并，清理分支，同步主分支	创建 PR 后停止，用户 Approve 后 AI 合并并清理
中断恢复	自动恢复，不询问	询问是否恢复

---

阶段工具约束

阶段	Edit/Write	Bash	说明
阶段1：读取 Jira	❌	❌	只调用 API，不修改任何文件
阶段2：分析问题	❌	❌	只读，不修改任何文件
阶段3：探索与审查方案	❌	❌	只读，不修改任何文件
阶段4：制定计划	❌	❌	只输出计划文本
阶段5：执行计划	✅	✅	前置 git 创建分支，再进行代码修改
阶段6：提交 PR	❌	✅（仅 git 命令）	不改代码，只执行提交

---

⚡ 快速参考（执行前必读，修改阶段时同步更新）

工具权限见上方「阶段工具约束」表。

阶段	👤 手动停止点	🤖 自动停止点	必须输出
0 前置检查	失败时终止；成功→自动进入阶段1	失败／P0 时终止；成功→自动继续	检查摘要
1 读取 Jira	完成→自动进入阶段2	自动继续	Jira 信息摘要
2 分析问题	存在性验证失败→停止；完成→连续执行2.5后⏸️ 确认进入阶段3	存在性验证失败→停止；完成→自动继续	根因＋难度等级
2.5 难度分级	极难→⛔ A/B 选择；非极难→追加到阶段2输出，不单独停顿	极难→⛔ 终止；非极难→自动继续	难度等级（追加输出）
3 探索与审查方案	⛔ 选方案后停；审查报告后停	审查超3轮→⛔ 暂停	方案表＋审查报告
4 制定计划	⛔ 输出计划后停	困难/高风险→⛔ 暂停	文件修改清单
5 执行计划	⛔ 执行后停等审查	困难→⛔ 暂停等审查	执行报告
6 提交 PR	⛔ 展示提交计划后停，用户确认后 AI 执行	自动 push＋Jira 回写	完成报告
7 合并 PR/MR 与收尾	⛔ 创建 PR 后停，用户 Approve 后 AI 合并	CI 通过后自动合并	合并状态／分支清理报告

---

通用原则

• 先调查再发言：没有代码证据不做判断，以事实而非猜测说话

• 主动提问：信息不足时每次只提 1 个最关键的问题，得到回答后再提下一个：

  [题干（一句话说清问题）]
  - A 选项一
  - B 选项二
  

  用户可直接回复「A」「B」等选项字母，AI 解析后继续。

• Jira 状态边界：研发角色只能将 issue 流转到「已修复」，禁止流转到「关闭」「验证通过」（这些状态由 QA 操作）

---

环境能力探索（跨平台自适应）

本工作流可在 Claude Code、OpenCode、Cursor 等不同平台运行。每个环境安装的 skill、插件、agent 不同。工作流应主动探索当前环境中可用的增强能力，在合适的阶段自动调用，而非仅依赖硬编码的 skill。

探索时机

阶段0完成后、阶段1开始前，执行一次环境能力扫描。扫描结果记入 state.json 的 enhanced_capabilities 字段，后续阶段直接引用，无需重复扫描。

探索方法（跨平台）

使用当前平台的 skill 发现能力，检查可用的 skill、agent、插件列表：

• Claude Code / OpenCode：查看系统提示中的 <available_items> 列表，或使用 skill 工具列出可用 skill
• Cursor：检查系统提示中注入的 skill 列表
• 通用降级：若上述方法均不可用，跳过增强能力探索，按原有流程执行

能力类型与阶段映射

扫描时，按以下能力类型关键词匹配可用 skill/agent 的 name 和 description：

能力类型	匹配关键词	对应阶段	用途
🔍 调试分析	debug, root-cause, investigate, systematic-debugging, 分析问题	阶段2	辅助根因定位
💡 方案设计	brainstorm, design, architect, 探索方案	阶段3	辅助方案探索
📝 计划制定	plan, writing-plan, 制定计划	阶段4	辅助计划细化
⚡ 代码执行	execute, executing-plan, subagent, parallel	阶段5	批量任务编排
🧪 测试驱动	test, tdd, test-driven	阶段5	先写测试再修复
🔧 构建修复	build-fix, build, linter	阶段5	构建/编译错误修复
✅ 完成验证	verify, verification, complete	阶段5→7	提交前验证
📋 代码审查	code-review, review, requesting-review	阶段6	代码审查
🌿 分支管理	worktree, branch, git-worktree	阶段1	工作区隔离

探索结果处理

• 匹配到增强能力：记录到 state.json，在对应阶段自动加载并调用（具体调用点见各阶段的「增强能力集成」小节）
• 未匹配到：静默跳过，按原有流程执行。不报错，不阻断
• 匹配到多个同类能力：优先选择 description 更具体的（如 systematic-debugging 优于通用 debug-workflow）

调用原则

• 渐进增强，不替代核心流程：增强能力是辅助手段，不改变阶段顺序和门控逻辑
• 只读阶段不因增强能力获得写权限：阶段工具约束表不变
• 增强能力失败不阻断流程：调用增强 skill/agent 报错时，记录警告，按原有流程继续

---

状态持久化（中断恢复）

恢复：检测到 state.json 时，[🤖 自动] 直接从 current_phase 继续；[👤 手动] 询问是否恢复。清理：完成后 state.json 设 current_phase: "completed"。

继续修复（阶段2重入）：触发词含「继续修复」「--retry」时，跳过阶段0/1，直接从阶段2重新分析。执行逻辑：

1. 读取已有 01-jira-info.md 作为 Jira 上下文，不再调用 API
2. 询问用户：「上次修复了什么？本次发现的新现象是？」（一次性收集补充上下文）
3. 将补充上下文写入 02-analysis.md 顶部的「本次迭代背景」区块，再重新执行分析
4. 重置 state.json：current_phase: 2，completed_phases: [0, 1]，清空 grade / selected_option / review_round / review_status
5. 阶段5前置创建分支时，在原分支名加 -v2（-v3、-v4……以此类推）

状态目录

.jira-fix/{JIRA-ID}/
├── state.json           ← 进度跟踪（含 mode、review_round、review_status 字段）
├── 00-branch.md         ← 阶段5前置（创建修复分支）输出
├── 01-jira-info.md      ← 阶段1输出
├── 02-analysis.md       ← 阶段2输出
├── 02-grade.md          ← 阶段2.5难度分级结果
├── 03-options.md        ← 阶段3输出（含方案对比 + 审查循环记录）
├── 04-plan.md           ← 阶段4输出
├── 05-execution.md      ← 阶段5输出
├── 06-report.md         ← 阶段6输出
└── 07-merge.md          ← 阶段7输出

state.json 结构

{
  "jira_id": "YNOTR-12345",
  "jira_url": "https://your-jira.example.com/browse/YNOTR-12345",
  "mode": "manual",
  "current_phase": 2,
  "completed_phases": [0, 1],
  "branch": "fix/jira-fix-YNOTR-12345",
  "grade": null,
  "selected_option": null,
  "review_round": 0,
  "review_status": null,
  "enhanced_capabilities": {},
  "started_at": "ISO_TIMESTAMP",
  "last_updated": "ISO_TIMESTAMP"
}

审查相关字段说明：

• review_round：0 = 未开始审查，1-3 = 第 N 轮审查（自动模式上限 3），用户说「继续审查」后可追加
• review_status：null = 未开始，"in_progress" = 审查中，"passed" = 审查通过，"failed_max_rounds" = 达到上限未通过

环境能力探索字段说明：

• enhanced_capabilities：阶段0完成后扫描的增强能力映射。key 为能力类型（如 "debug"、"test"、"verify"），value 为匹配到的 skill/agent 名称。空对象 {} 表示未探索或未发现增强能力

---

阶段0：前置检查

任一检查失败则中断流程

执行步骤

1. 识别模式：解析触发词，识别 --manual / --force / --resume，写入 state.json
2. mcp 连通检查：调用 jira_get_issue（仅获取标题/优先级）；失败立即终止，提示检查配置/PAT/URL/网络
3. P0 拦截（仅自动）：优先级为 P0 → 终止，提示改用手动模式
4. Git 检查：[🤖] 工作区不净 → 自动 stash；[👤] 工作区不净 → 提示用户处理

输出字段

Jira ID、Issue 标题、优先级、执行模式、mcp 状态、Git 状态。

[👤 手动 / 🤖 自动] 直接进入阶段1：读取 Jira 信息，无需确认。

---

阶段1：读取 Jira 信息

原则

• 优先获取最新数据（--live 模式）
• API 不可用时读取本地缓存
• 复用 jira-read skill 的统一逻辑
• 工具限制：✅ mcp-atlassian API / jira-read；❌ Edit/Write/Bash

调用 jira-read {JIRA-ID} --live，降级读本地缓存，再降级手动提供/报错终止。保存到 .jira-fix/{JIRA-ID}/01-jira-info.md，更新 state.json。

提取：Jira ID、标题、优先级、状态、描述、复现步骤、期望/实际结果、附件、评论。

输出字段

Jira ID、标题、优先级、状态、数据来源、问题描述、复现步骤、期望/实际结果、评论摘要。

[👤 手动 / 🤖 自动] 直接进入阶段2：分析问题，无需确认。

---

阶段2：分析问题

只读分析，不修改代码

🔌 增强能力集成：若环境探索发现了「🔍 调试分析」类能力（如 systematic-debugging、debug-workflow、OMC debugger agent 等），在根因分析环节加载并遵循其方法论（如假设驱动调查、证据链构建）。未发现则按下述原有流程执行。

原则

• 深度分析，追问「为什么」至少 3 次
• 结构化输出，中文描述
• [👤 手动] 信息不足时主动提问，格式见「通用原则 → 主动提问」
• 工具限制：✅ Read/Grep/SemanticSearch；❌ Edit/Write/Bash

分析维度

第一步：存在性验证（门控，必须最先执行）

用 Read/Grep/SemanticSearch 搜索与 Jira 描述相关的代码，判断：

结论	处理方式
✅ 问题存在	继续后续分析维度
❌ 问题已不存在	报告「当前代码库中未发现该问题，可能已被修复或逻辑已变更」，附相关代码位置，停止分析，更新 Jira 评论并等待用户确认
⚠️ Jira 描述与代码不符	报告「代码行为与 Jira 描述存在出入」，列出实际发现，等待用户重新确认问题描述

• 问题现象：复现步骤、期望 vs 实际结果
• 代码定位：Grep/Glob/SemanticSearch 组合搜索关键代码
• 根因分析：数据流（操作→组件→函数→状态→渲染）+ 调用链，区分直接原因与根本原因

根因分析后立即执行：行业通病评估（门控）

判断根因是否触及平台/语言/协议/标准的固有限制；若有疑虑，用 WebSearch 调研业界现状：

结论	处理方式
🚫 行业公认难题，无可行解	输出【行业通病评估报告】，停止流程，不进入阶段3；在 Jira 写评论说明结论
⚠️ 存在局限但有绕过方案	在阶段3方案探索中将绕过方案列为候选，继续后续分析
✅ 非行业通病，属可修复问题	继续后续分析

行业通病评估报告格式：

【行业通病评估】
- 问题本质：...（根因一句话总结）
- 行业现状：...（已知公开记录、主流框架态度、大厂处理方式）
- 调研结论：该问题属于 [平台限制/协议约束/语言特性/标准规范]，业界目前无可行解
- 建议：接受现状 / 评估替代方案（非修复）/ 与产品对齐预期
流程已中断，不进入方案探索阶段。

• 影响范围：功能、平台（Web/Mobile）、模块、连带影响
• 难度预判：预估改动文件数 + 根因清晰度（清晰/基本清晰/模糊/未知，供阶段2.5使用）

输出字段

存在性验证结论、问题现象（复现/期望/实际）、代码定位（路径:行号+说明）、根因（直接+根本+调用链）、行业通病评估结论、影响范围（模块/平台/连带）、难度预判。保存到 .jira-fix/{JIRA-ID}/02-analysis.md

[👤 手动] 立即连续执行阶段2.5：难度分级，将分级结果追加到本输出末尾，然后附上： 「⏸️ 问题分析 + 难度分级完成（等级：X）。进入阶段3：探索与审查方案，回复「确认」继续。」 [🤖 自动] 自动进入阶段2.5，无需用户确认。

Red Flags — 禁止行为

• 跳过存在性验证，直接进入问题现象分析
• 存在性验证结论为「不存在/描述不符」但仍继续分析
• 以「Jira 描述已经很清楚」为由跳过代码定位，直接进入方案评估
• 以「这是常见 bug」为由跳过根因分析，直接复用历史方案
• 根因分析后跳过行业通病评估，直接进入影响范围
• 行业通病评估结论为「无可行解」但仍进入阶段3
• 分析阶段修改代码（本阶段严格只读，违反阶段工具约束）

---

阶段2.5：难度分级 + 模式决策网关

基于阶段2的分析结果，使用规则制判定难度等级，决定后续行为

🔴 极难触发条件（满足任一即为极难）

条件	判断依据
根因未知	分析后仍无法定位根本原因（知道大概模块但无法定位到具体逻辑）
涉及架构变更	需要重构模块间通信、变更设计模式、调整核心数据结构
涉及数据迁移	需要数据库 schema 变更或数据格式迁移
API 协议变更	需要修改对外接口签名，影响调用方
改动范围过大	预估改动文件 >10 个 或 预估行数变更 >500 行
跨仓库/跨服务	需要在多个独立 Git 仓库中协同修改

等级判定（未命中极难条件时）

• 预估文件 ≤ 3 个，根因清晰 → 🟢 容易
• 预估文件 4–10 个，根因基本清晰 → 🟡 中等
• 预估文件 ≤ 10 个，根因较清晰但改动较多 → 🟠 困难

模式 × 等级 → 行为

等级	🤖 自动模式	👤 手动模式
🟢 容易	✅ 正常执行	💡 提示「此问题较简单，可切换自动模式」，继续手动流程
🟡 中等	✅ 正常执行	💡 提示「此问题风险可控，可切换自动模式」，继续手动流程
🟠 困难	✅ 执行，阶段5完成后暂停等用户审查代码再提交	✅ 正常手动流程
🔴 极难	❌ 终止，输出标记报告	⚠️ 风险提示，用户选择 A/B

输出字段

难度等级（🟢/🟡/🟠/🔴）、命中条件列表、行为提示（终止报告/风险选项 A-B/建议切换模式）、后续行动建议。分级结果保存到 .jira-fix/{JIRA-ID}/02-grade.md，更新 state.json "grade" 字段

[👤 手动] 非极难时：分级结果已追加到阶段2输出，不再单独停顿，直接由阶段2出口的 ⏸️ 统一等待用户确认。 [👤 手动] 极难选 B（继续）时，附上：「⚠️ 已知晓高风险，进入阶段3：探索与审查方案，回复「确认」继续，或回复「A」终止。」 [🤖 自动] 自动进入阶段3，无需用户确认。

---

阶段3：探索与审查方案

🔌 增强能力集成：若环境探索发现了「💡 方案设计」类能力（如 brainstorming、OMC analyst/architect agent 等），在方案探索环节加载并辅助多方案对比分析。未发现则按下述原有流程执行。

[🤖 自动模式] 自动选择

自动生成 2-3 个方案，优先选：更彻底解决 > 符合规范最佳实践 > 改善代码质量 > 改动较少。

[👤 手动模式] 等用户选择

若缺少选型偏好，先提出 1 个最关键的问题，得到回答后再输出方案对比与推荐。

输出格式

1. 开头：方案对比表
2. 中间：每个方案详细展开（见下方「每个方案包含」）
3. 结尾：再次输出方案对比表，便于快速回顾

方案	描述	优点	缺点	复杂度	推荐度
方案1	...	...	...	低/中/高	⭐⭐⭐⭐⭐
方案2	...	...	...	低/中/高	⭐⭐⭐

每个方案包含

• 核心思路（1-2 句话）
• 需要修改的文件/模块
• 优点（≥2）、缺点（≥1）
• 复杂度 + 风险等级（低/中/高）、适用场景

[🤖 自动] 自动选定最优方案后进入审查；[👤 手动] 等用户选定后进入审查。保存到 .jira-fix/{JIRA-ID}/03-options.md

⛔ [手动模式 — 阶段3 方案选择出口] 输出方案对比表后立即停止，在表末必须附上： 「请选择一个方案（回复方案编号，如「方案1」），AI 将进入方案审查。」 🤖 [自动模式] 自动选定最优方案，直接进入审查。

方案审查 — 循环审查机制（选定方案后执行）

对选定方案深度核查，循环审查直到通过；工具限制：✅ Read；❌ Edit/Write/Bash

审查维度（每轮必须覆盖）

1. 解决有效性：是否完整覆盖根因、能否高效高质量解决问题、核心逻辑与关键实现点
2. 副作用与风险：改动是否在其他模块引发新问题（功能副作用）、是否带来性能/安全/可维护性问题（非功能副作用）、已识别问题有无缓解措施
3. 实现可行性：改动范围、依赖关系、涉及文件/模块是否明确可执行
4. 代码规范符合度：是否符合项目现有模式和最佳实践

审查结论（二级制）

结论	判定标准	后续动作
✅ 通过	四项审查维度均无阻断问题，仅存在可接受的低风险	进入阶段4
❌ 不通过	任一维度存在需解决的问题或不可接受的风险	进入优化→重新审查循环

阻断问题判定指引（满足任一即为 ❌ 不通过）：

• 方案无法完整覆盖阶段2确定的根因（核心逻辑不完整）
• 存在已识别但未提出缓解措施的中/高风险
• 涉及的修改文件或依赖关系不明确，无法据此制定可执行计划
• 与项目现有设计模式或编码规范明显冲突
• 可能引入新 bug 或破坏现有功能的副作用未被处理

非阻断问题（可标注为建议，但不阻止通过）：

• 已有缓解措施的低风险项
• 代码风格偏好（不影响正确性）
• 可在后续迭代中优化的性能改进

循环流程

方案选定 → 审查（第 N 轮）→ 输出审查报告
                ↓
          审查结论判定
           ├── ✅ 通过 → 进入阶段4
           └── ❌ 不通过 → 方案优化 → 回到审查（第 N+1 轮）
                              ↓
                        达到循环上限？
                         ├── 否 → 继续循环
                         └── 是 → 超限处理

[🤖 自动模式] 审查循环

• 判定者：AI 自动判定通过/不通过
• 不通过时：AI 根据审查报告中的问题清单自动优化方案，输出优化说明，然后重新审查
• 循环上限：3 轮（第 1 轮为初次审查，最多优化 2 次后重审）
• 超限处理：
  • 非批量模式：暂停，输出 3 轮审查摘要（每轮的问题与优化记录），等用户介入决策。用户可选操作：
    • 说「继续审查」→ 追加审查轮次（上限重置为 +3 轮）
    • 说「重选方案」→ 回到方案选择环节
    • 手动调整方案方向后说「重新审查」
  • 批量模式：标记该 issue 为「审查未通过（超限）」，跳过后续阶段，记入批量报告，继续处理下一个 issue

[👤 手动模式] 审查循环

• 判定者：用户判定通过/不通过
• AI 输出审查报告后，等用户响应：
  • 用户说「通过」「确认」「OK」→ 进入阶段4
  • 用户说「修改方案」「完善方案」「优化方案」→ 按用户指导优化方案，重新审查
  • 用户说「重选方案」→ 回到方案选择环节
• 循环上限：无（用户自主控制）

审查报告输出字段

每轮审查必须输出：

• 审查轮次：第 N 轮（共 M 轮上限）
• 四维度评估：解决有效性 / 副作用与风险 / 实现可行性 / 代码规范符合度（各维度标注 ✅ 或 ❌ + 具体问题）
• 问题清单：不通过时列出所有需解决的问题（编号 + 问题描述 + 严重程度）
• 审查结论：✅ 通过 / ❌ 不通过
• [❌ 不通过时] 优化建议：针对每个问题的具体改进方向

保存到 .jira-fix/{JIRA-ID}/03-options.md（追加审查记录）

⛔ [手动模式 — 阶段3 审查出口] 输出审查报告后立即停止，在报告末必须附上： 「⏸️ 方案审查完成。是否进入阶段4：制定计划？回复「确认」继续，或说「修改方案」重新审查。」 🤖 [自动模式] AI 自动判定通过/不通过；通过进入阶段4，不通过自动优化后重审（上限3轮，超限暂停）。

Red Flags — 禁止行为

• 只生成 1 个方案，以「方向已明确」为由跳过方案对比
• [👤 手动] 用户未选方案时自行推进到审查
• 跳过方案审查直接进入阶段4（风险未识别）
• 在探索与审查方案阶段修改代码（违反只读约束）
• [🤖 自动] 审查不通过时不优化方案，直接进入阶段4
• [🤖 自动] 审查循环超过 3 轮上限仍不暂停
• [🤖 自动] 优化方案时未输出优化说明，导致审查记录不可追溯
• [🤖 自动] 所有方案审查风险 > 中时不暂停，直接执行
• [👤 手动] 用户未明确判定通过/不通过，AI 自行推进

---

阶段4：制定计划

详细可执行的修改计划

🔌 增强能力集成：若环境探索发现了「📝 计划制定」类能力（如 writing-plans、OMC planner agent 等），加载并辅助生成更结构化的执行计划。未发现则按下述原有流程执行。

计划必须包含：① 根因回顾 ② 方案回顾 ③ 架构设计（可选 Mermaid）④ 文件修改清单（表格：文件/内容/类型）⑤ 修改顺序（考虑依赖关系）⑥ 测试场景（Web/Mobile/兼容性）⑦ 影响范围（服务层/Web/Mobile/风险等级）⑧ 回滚方案

确认方式

场景	行为
[🤖 自动] 普通情况	自动确认，立即进入阶段5
[🤖 自动] 难度🟠困难 或 方案风险>中	输出计划后暂停，等用户确认后继续
[👤 手动] 普通情况	等用户确认
[👤 手动] 极难选B	强制要求用户二次确认「我已知晓风险，继续执行」后才进阶段5

保存到 .jira-fix/{JIRA-ID}/04-plan.md

⛔ [手动模式 — 阶段4 出口] 输出计划后立即停止，在计划末必须附上： 「⏸️ 阶段4（制定计划）完成。是否进入阶段5：执行计划？回复「确认」继续，或说明需要调整。」 🤖 [自动模式] 普通情况自动确认；困难等级或方案风险>中时暂停等用户确认后再进入阶段5。

Red Flags — 禁止行为

• 制定计划阶段修改代码（违反只读约束，见「阶段工具约束」表）
• [🤖 自动] 困难等级或高风险方案未暂停，直接跳入阶段5
• 计划缺少测试场景或回滚方案就推进到阶段5
• [👤 手动] 未等用户确认计划就进入执行

---

阶段5：执行计划

前置：创建修复分支

计划已确认、代码修改前执行；此时已明确所有涉及工程与文件路径。

分支命名：fix/jira-fix-[JIRA-ID]，如 fix/jira-fix-YNOTR-12167

根据阶段4计划的「文件修改清单」，识别涉及的所有 Git 工程，为每个工程创建修复分支：

[🤖 自动] 扫描文件路径 → 匹配各工程 .git 根目录 → 批量 git checkout -b fix/jira-fix-[JIRA-ID]；失败则报错终止。

[👤 手动 — 单工程] 直接创建分支，无需确认，创建后附上：「✅ 修复分支已创建：fix/jira-fix-[JIRA-ID]，开始执行代码修改。」 [👤 手动 — 多工程] 展示分支列表（工程 / 基础分支 / 分支名），用户确认后批量创建，附上：「⏸️ 多工程分支已创建，即将开始代码修改，回复「确认」继续。」

保存到 .jira-fix/{JIRA-ID}/00-branch.md，更新 state.json branch 字段。

[🤖 自动] 自动继续执行计划。

---

严格按计划执行，逐步更新 TODO 状态

🔌 增强能力集成：

• 若发现「🧪 测试驱动」类能力（如 test-driven-development、OMC test-engineer agent），优先为 bug 编写复现测试用例，再进行修复（红→绿→重构）
• 若发现「⚡ 代码执行」类能力（如 executing-plans、subagent-driven-development），对多文件修改任务进行批量编排
• 若发现「🔧 构建修复」类能力（如 build-fix、OMC build-fixer agent），在 Linter/TypeScript 检查失败时自动调用
• 未发现以上能力则按原有流程执行

前置：确认在 fix/jira-fix-[JIRA-ID] 分支，工作区干净。用 TodoWrite 追踪任务状态（pending/in_progress/completed）。

代码质量：函数职责单一、命名清晰（函数用动词/变量用名词）、向后兼容。

修复注释标注：每处代码改动必须在修改行附近添加追踪注释，格式：

// fix [JIRA-ID]

示例：// fix YNOTR-12721

• 注释紧邻修改的代码块（修改前一行或同行尾部均可）
• 多处改动各自标注，不可只在文件顶部统一写一次
• 语言注释符随语言变化（Python 用 #，HTML 用 <!-- -->，SQL 用 --）

代码质量检查

1. Linter 检查：修改后用 ReadLints 检查，新引入的错误必须修复
2. TypeScript 检查（自动检测）：项目存在 tsconfig.json 时自动调用 typescript-check skill，新引入类型错误必须修复

[🤖 自动模式] 额外能力

多项目代码修改：根据文件路径前缀定位对应项目，各项目独立检查 Linter，记录每个项目修改文件及行数统计。

报告生成：执行完成后自动生成 reports/[JIRA-ID]-analysis.md，包含：基本信息、问题分析、根因、解决方案、修改文件清单、遇到的问题、测试建议。

执行后行为

场景	行为
[🤖 自动] 普通情况	自动进入阶段6
[🤖 自动] 难度🟠困难	暂停，输出执行摘要，等用户审查代码后确认继续
[👤 手动] 普通情况	等用户确认后进入阶段6
[👤 手动] 极难选B	暂停，等用户审查代码，不自动提交

执行报告

执行完成后必须输出：已修改文件及关键改动说明、偏离计划的调整（如有需说明原因）、验证要点/自查清单。保存到 .jira-fix/{JIRA-ID}/05-execution.md

⛔ [手动模式 — 阶段5 出口] 输出执行报告后立即停止，在报告末必须附上： 「⏸️ 阶段5（执行计划）完成，请审查代码。是否进入阶段6：提交 PR？回复「确认」继续，或告知需要调整。」 🤖 [自动模式] 普通情况自动进入阶段6；困难等级时暂停等用户审查代码后确认。

Red Flags — 禁止行为

• 跳过 Linter 检查，以「只是逻辑改动」为由认为不必要
• 代码改动未添加 // fix [JIRA-ID] 注释，导致修复点无法追踪
• 偏离计划修改了计划外文件，未说明原因
• [🤖 自动] 遇到计划外问题未暂停，自行决策继续
• 执行完成未输出执行报告直接进入阶段6

---

阶段6：提交 PR

🔌 增强能力集成：

• 若发现「✅ 完成验证」类能力（如 verification-before-completion、OMC verifier agent），在提交前执行独立验证（运行测试、确认修复、检查回归），有证据再提交
• 若发现「📋 代码审查」类能力（如 requesting-code-review、OMC code-reviewer agent），提交后自动发起代码审查
• 未发现以上能力则按原有流程执行

[🤖 自动模式] 自动提交

1. 收集提交信息（Jira ID、根因、修复方案、修改文件、报告路径）
2. 调用 git-commit SKILL（execute=true，自动模式）：自动 add / commit / push
3. Jira 状态自动回写：调用 jira_get_transitions，匹配「修复完成」（即流转到"已修复"状态）；禁止流转到"关闭"或"验证通过"——研发角色只能将 issue 标记为"已修复"，"关闭"由 QA 验证后操作；无匹配时跳过记警告；调用 jira_add_comment 写修复评论

修复评论字段：修复分支、Commit、根因、修复方案、修改文件、分析报告路径、验证场景（功能/边界/回归各 ≥2）。

[👤 手动模式] 确认后提交

收集提交信息，展示将要执行的 commit 计划（分支、commit message、修改文件、验证场景各 ≥2 条）和 Jira 回写内容，等用户确认后，AI 执行 add / commit / push + Jira 状态回写。修复评论字段同自动模式。

⛔ [手动模式 — 阶段6 出口] 展示提交计划和验证场景后立即停止，在末尾必须附上： 「⏸️ 提交计划已就绪。确认后 AI 将执行 push + Jira 状态回写。回复「确认」继续，或告知需要修改。」 🤖 [自动模式] 无需确认，自动执行 push + Jira 状态回写（仅流转到「已修复」，禁止流转「关闭」或「验证通过」）。

Commit Message 格式

<type>(<scope>): <Jira-ID> <subject>

示例：fix(ai-summary): YNOTR-12167 修复分享链接中AI摘要按钮显示问题

Type：fix、feat、refactor、perf、style、docs、test　Scope 示例：ai-summary、share、auth、api、ui、core

完成输出字段

修复分支、Commit Hash、推送状态、Jira 回写状态、分析报告路径；多项目时用表格。错误处理：回写失败不阻断流程，仅输出警告并记录到报告。

保存到 .jira-fix/{JIRA-ID}/06-report.md

Red Flags — 禁止行为

• [👤 手动] 未等用户确认直接执行 git push
• Jira 回写失败后未输出警告，静默跳过
• Commit message 遗漏 Jira ID
• 多项目场景只提交了部分项目

---

阶段7：合并 PR/MR 与收尾

push 成功后，创建 PR/MR，完成合并、分支清理与主分支同步

🔌 增强能力集成：若发现「📋 代码审查」类能力（如 requesting-code-review、OMC code-reviewer agent），创建 PR 后自动发起正式 Code Review 流程。

创建 PR/MR

使用 gh pr create（GitHub）或平台对应命令创建 PR，标题格式与 commit message 保持一致：

fix(<scope>): <subject> [JIRA-ID]

PR 描述必须包含：根因、修复方案、修改文件清单、验证场景（功能/边界/回归各 ≥2）、Jira 链接。

[🤖 自动模式] 自动合并

1. 创建 PR，等待 CI 检查通过
2. CI 通过后执行 gh pr merge --merge
3. 删除远程修复分支：git push origin --delete fix/jira-fix-[JIRA-ID]
4. 切换并同步主分支：git checkout main && git pull origin main
5. 删除本地修复分支：git branch -d fix/jira-fix-[JIRA-ID]

[👤 手动模式] 确认后合并

1. 创建 PR，展示 PR URL 和描述摘要，立即停止，等用户完成 Code Review 并确认合并
2. 用户确认（说「合并」「merge」「OK」等）后，AI 依次执行：
   • gh pr merge --merge
   • 删除远程修复分支
   • 切换并同步主分支（git checkout main && git pull origin main）
   • 删除本地修复分支

⛔ [手动模式 — 阶段7 出口] 创建 PR 并展示 URL 后立即停止，在末尾必须附上： 「⏸️ PR 已创建，请完成 Code Review。是否合并并清理分支？回复「确认」继续。」 🤖 [自动模式] CI 通过后自动合并，执行分支清理与主分支同步，无需用户干预。

完成输出字段

PR URL、合并状态、分支清理状态（本地/远程）、主分支同步状态。保存到 .jira-fix/{JIRA-ID}/07-merge.md，同时更新 state.json current_phase: "completed"。

Red Flags — 禁止行为

• [👤 手动] 未等用户确认合并直接执行 gh pr merge
• CI 未通过时强制合并（不加 --admin 或 --force）
• 合并后未清理本地和远程修复分支
• 合并后未同步主分支

---

安全机制（自动模式）

修改前自动 stash；警告阈值：>10文件 或 >500行；阻断阈值：>20文件 或 >1000行（需 --force 解除）；Linter 错误自动阻断；审查循环上限：3 轮（超限暂停或标记跳过）；记录所有自动决策日志。

---

常见错误

错误	后果	修正
跳过存在性验证直接分析根因	分析不存在的问题、浪费上下文	阶段2第一步必须是存在性验证
存在性验证为「不存在/描述不符」仍继续	方向全错	立即停止并更新 Jira 评论，等待用户确认
跳过行业通病评估进入方案探索	为无解问题浪费修复资源	根因分析后必须执行行业通病评估
行业通病评估为「无可行解」仍进入阶段3	产出无意义方案	输出评估报告并在 Jira 写评论后中断
跳过代码定位直接给方案	方案治标不治本	返回阶段2完成根因定位
自动模式遇极难仍继续执行	高风险改动失控	触发阶段2.5网关，终止流程
手动模式跳过方案确认直接制定计划	执行错误方案	等用户选择后再进阶段4
审查不通过仍直接进入阶段4	带问题的方案进入执行，返工成本高	必须循环审查直到通过或达到上限
自动模式审查循环超过3轮不暂停	无限循环浪费资源，方案可能根本不可行	达到3轮上限必须暂停等用户介入（批量模式标记跳过）
审查循环中未记录每轮优化内容	审查过程不可追溯，用户无法理解决策链路	每轮审查必须输出完整审查报告并追加到 03-options.md
增强能力探索失败后阻断流程	不必要的中断	增强能力是可选的，探索失败必须静默跳过
增强能力突破阶段工具约束	只读阶段被写入	增强能力不改变阶段工具约束（如阶段2仍禁止 Edit/Write）
执行完成未做 Linter 检查	引入新的代码错误	ReadLints 是必须步骤，不可跳过
代码改动缺少 // fix [JIRA-ID] 注释	修复点无法追踪，Code Review 难以定位	每处改动附近必须标注
分析阶段使用 Edit/Write 修改代码	破坏只读约束	见「阶段工具约束」表

---

批量修复

将每个 Jira bug 作为独立任务，交由任务编排工具（如 /ralph、/autopilot、/ultrawork，以当前平台为准）依次调用 jira-fix [URL]。编排工具负责：单个失败不阻断后续、跟踪整体进度、汇总结果。

批量模式下的审查超限处理：当某个 issue 的方案审查循环达到 3 轮上限仍未通过时，标记该 issue 为「审查未通过（超限）」，跳过后续阶段（不进入阶段4/6/7），在批量报告中记录该 issue 的 3 轮审查摘要，继续处理下一个 issue。

示例（以 /ralph 为例）：

/ralph 批量修复以下 Jira bug：
YNOTR-12167 YNOTR-12168 https://your-jira.example.com/browse/YNOTR-12169