// 当用户说「修复这个 bug [URL]」「帮我修复 [URL]」「jira-fix [URL]」「自动修复 [URL]」「强制修复 [URL]」「继续修复」「从上次继续」时触发。适用于从 Jira 链接出发、对单个 bug 进行端到端修复的场景。
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | jira-fix-workflow |
| version | 3.9.0 |
| user-invocable | true |
| description | 当用户说「修复这个 bug [URL]」「帮我修复 [URL]」「jira-fix [URL]」「自动修复 [URL]」「强制修复 [URL]」「继续修复」「从上次继续」时触发。适用于从 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 提示，工作区提示用户处理 |
| 阶段1.5：理解对齐 | 跳过，直接进入阶段2 | 复述理解 + 列歧义点，等用户确认后进入阶段2 |
| 阶段2.5：难度分级 | 极难 → 终止，输出标记报告 | 极难 → 列出风险，用户选择 A/B |
| 阶段3：探索与审查方案 | AI 自动探索并循环审查（≤3轮），通过后自动进阶段4；超限暂停（批量模式标记跳过） | 输出方案表→用户选择→审查→用户判定通过/不通过→循环至通过后进阶段4 |
| 阶段4：制定计划 | 自动确认，直接进阶段5 | 等用户确认 |
| 阶段5：执行计划 | 前置创建分支 + 执行 + Linter + 自动生成分析报告 | 单工程：直接创建分支，无需确认；多工程：展示分支计划后确认创建 + 执行 + Linter |
| 阶段6：检查验证 | 自动判定通过/未达标；未达标自动回退（最多 2 次，超限暂停） | 等用户确认通过后进入阶段7 |
| 阶段7：提交 PR/MR | 自动 push + 创建 PR/MR + Jira 状态回写 | 展示提交计划，用户确认后 AI 执行 push + 创建 PR/MR |
| 阶段8：Review 与合并 | CI 通过后自动合并，清理分支，同步主分支 | PR/MR 已在阶段7创建，等待 Code Review，用户确认后 AI 合并并清理 |
| 中断恢复 | 自动恢复，不询问 | 询问是否恢复 |
| 阶段 | Edit/Write | Bash | 说明 |
|---|---|---|---|
| 阶段1：读取 Jira | ❌ | ❌ | 只调用 API，不修改任何文件 |
| 阶段1.5：理解对齐 | ❌ | ❌ | 禁止代码探索，仅基于 Jira 数据输出理解复述 |
| 阶段2：分析问题 | ❌ | ❌ | 只读，不修改任何文件 |
| 阶段3：探索与审查方案 | ❌ | ❌ | 只读，不修改任何文件 |
| 阶段4：制定计划 | ❌ | ❌ | 只输出计划文本 |
| 阶段5：执行计划 | ✅ | ✅ | 前置 git 创建分支，再进行代码修改 |
| 阶段6：检查验证 | ❌ | ✅（仅测试命令） | 只读验证，不修改代码 |
| 阶段7：提交 PR/MR | ❌ | ✅（仅 git/平台 CLI 命令） | 不改代码，执行提交与 PR/MR 创建 |
| 阶段8：Review 与合并 | ❌ | ✅（仅平台 CLI 合并命令） | 等待 CI + Code Review，用户确认后合并 |
工具权限见上方「阶段工具约束」表。
| 阶段 | 👤 手动停止点 | 🤖 自动停止点 | 必须输出 |
|---|---|---|---|
| 0 前置检查 | 失败时终止；成功→自动进入阶段1 | 失败／P0 时终止；成功→自动继续 | 检查摘要 |
| 1 读取 Jira | 完成→自动进入阶段1.5 | 自动继续进入阶段1.5 | Jira 信息摘要 |
| 1.5 理解对齐 | ⛔ 输出理解复述后停，等用户确认后进入阶段2 | 跳过，直接进入阶段2 | 问题复述＋歧义点 |
| 2 分析问题 | 存在性验证失败→停止；完成→连续执行2.5后⏸️ 确认进入阶段3 | 存在性验证失败→停止；完成→自动继续 | 根因＋难度等级 |
| 2.5 难度分级 | 极难→⛔ A/B 选择；非极难→追加到阶段2输出，不单独停顿 | 极难→⛔ 终止；非极难→自动继续 | 难度等级（追加输出） |
| 3 探索与审查方案 | ⛔ 选方案后停；审查报告后停 | 审查超3轮→⛔ 暂停 | 方案表＋审查报告 |
| 4 制定计划 | ⛔ 输出计划后停 | 困难/高风险→⛔ 暂停 | 文件修改清单 |
| 5 执行计划 | ⛔ 执行后停等审查 | 困难→⛔ 暂停等审查 | 执行报告 |
| 6 检查验证 | ⛔ 输出验证结果后停，等用户确认 | 通过→自动进阶段7；未达标→自动回退（≤2次，超限暂停） | 验证结果 |
| 7 提交 PR/MR | ⛔ 展示提交计划后停，用户确认后 AI 执行 push + 创建 PR/MR | 自动 push + 创建 PR/MR + Jira 回写 | 完成报告＋PR/MR URL |
| 8 Review 与合并 | ⛔ 等待 Code Review，用户确认后 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、插件列表：
<available_items> 列表，或使用 skill 工具列出可用 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 | 阶段6 | 检查验证 |
| 📋 代码审查 | code-review, review, requesting-review | 阶段7 | 代码审查 |
| 🌿 分支管理 | worktree, branch, git-worktree | 阶段1 | 工作区隔离 |
systematic-debugging 优于通用 debug-workflow）恢复：检测到 state.json 时，[🤖 自动] 直接从 current_phase 继续；[👤 手动] 询问是否恢复。清理：完成后 state.json 设 current_phase: "completed"。
继续修复（阶段2重入）：触发词含「继续修复」「--retry」时，跳过阶段0/1，直接从阶段2重新分析。执行逻辑：
01-jira-info.md 作为 Jira 上下文，不再调用 API02-analysis.md 顶部的「本次迭代背景」区块，再重新执行分析current_phase: 2，completed_phases: [0, 1]，清空 grade / selected_option / review_round / review_status-v2（-v3、-v4……以此类推）.jira-fix/{JIRA-ID}/
├── state.json ← 进度跟踪（含 mode、review_round、review_status 字段）
├── 00-branch.md ← 阶段5前置（创建修复分支）输出
├── 01-jira-info.md ← 阶段1输出
├── 01.5-alignment.md ← 阶段1.5输出（理解对齐，手动模式产生）
├── 02-analysis.md ← 阶段2输出
├── 02-grade.md ← 阶段2.5难度分级结果
├── 03-options.md ← 阶段3输出（含方案对比 + 审查循环记录）
├── 04-plan.md ← 阶段4输出
├── 05-execution.md ← 阶段5输出
├── 06-verification.md ← 阶段6输出（检查验证）
├── 07-report.md ← 阶段7输出（提交 PR）
└── 08-merge.md ← 阶段8输出（合并 PR/MR）
{
"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 名称。空对象 {} 表示未探索或未发现增强能力任一检查失败则中断流程
--manual / --force / --resume，写入 state.jsonjira_get_issue（仅获取标题/优先级）；失败立即终止，提示检查配置/PAT/URL/网络Jira ID、Issue 标题、优先级、执行模式、mcp 状态、Git 状态。
[👤 手动 / 🤖 自动] 直接进入阶段1：读取 Jira 信息，无需确认。
--live 模式）jira-read skill 的统一逻辑调用 jira-read {JIRA-ID} --live，降级读本地缓存，再降级手动提供/报错终止。保存到 .jira-fix/{JIRA-ID}/01-jira-info.md，更新 state.json。
提取：Jira ID、标题、优先级、状态、描述、复现步骤、期望/实际结果、附件、评论。
Jira ID、标题、优先级、状态、数据来源、问题描述、复现步骤、期望/实际结果、评论摘要。
[👤 手动 / 🤖 自动] 直接进入阶段1.5：理解对齐，无需确认。
原则：基于阶段1读取的 Jira 数据，用自己的话复述理解，暴露歧义点和关键假设；在进入技术分析前与用户对齐。禁止读取代码库。
[🤖 自动] 跳过本阶段，直接进入阶段2：分析问题，将阶段1读取的内容视为已确认的问题描述。
[👤 手动] 必须完成本阶段并获用户确认后，才能进入阶段2。
【问题复述】我理解这个 Bug 是：...（一句话，不含技术判断）
【关键要素】触发条件：... / 期望行为：... / 实际行为：... / 复现环境：...
【歧义与假设】（若有）
[问题] A [...] B [...]
请确认我的理解是否准确，或补充 Jira 描述中遗漏的信息。
保存到 .jira-fix/{JIRA-ID}/01.5-alignment.md，更新 state.json。
工具限制：❌ Read/Grep/SemanticSearch/Edit/Write/Bash（禁止一切文件读写与代码探索，仅基于阶段1输出）
⛔ [手动模式 — 阶段1.5 出口] 输出后立即停止，等用户确认理解正确（或补充信息）后，才能进入阶段2。 🤖 [自动模式] 跳过本阶段，直接进入阶段2。
只读分析，不修改代码
🔌 增强能力集成：若环境探索发现了「🔍 调试分析」类能力（如 systematic-debugging、debug-workflow、OMC debugger agent 等），在根因分析环节加载并遵循其方法论（如假设驱动调查、证据链构建）。未发现则按下述原有流程执行。
第一步：存在性验证（门控，必须最先执行）
用 Read/Grep/SemanticSearch 搜索与 Jira 描述相关的代码，判断：
| 结论 | 处理方式 |
|---|---|
| ✅ 问题存在 | 继续后续分析维度 |
| ❌ 问题已不存在 | 报告「当前代码库中未发现该问题，可能已被修复或逻辑已变更」，附相关代码位置，停止分析，更新 Jira 评论并等待用户确认 |
| ⚠️ Jira 描述与代码不符 | 报告「代码行为与 Jira 描述存在出入」，列出实际发现，等待用户重新确认问题描述 |
根因分析后立即执行：行业通病评估（门控）
判断根因是否触及平台/语言/协议/标准的固有限制；若有疑虑，用 WebSearch 调研业界现状：
| 结论 | 处理方式 |
|---|---|
| 🚫 行业公认难题，无可行解 | 输出【行业通病评估报告】，停止流程，不进入阶段3；在 Jira 写评论说明结论 |
| ⚠️ 存在局限但有绕过方案 | 在阶段3方案探索中将绕过方案列为候选，继续后续分析 |
| ✅ 非行业通病，属可修复问题 | 继续后续分析 |
行业通病评估报告格式：
【行业通病评估】
- 问题本质：...（根因一句话总结）
- 行业现状：...（已知公开记录、主流框架态度、大厂处理方式）
- 调研结论：该问题属于 [平台限制/协议约束/语言特性/标准规范]，业界目前无可行解
- 建议：接受现状 / 评估替代方案（非修复）/ 与产品对齐预期
流程已中断，不进入方案探索阶段。
存在性验证结论、问题现象（复现/期望/实际）、代码定位（路径:行号+说明）、根因（直接+根本+调用链）、行业通病评估结论、影响范围（模块/平台/连带）、难度预判。保存到 .jira-fix/{JIRA-ID}/02-analysis.md
[👤 手动] 立即连续执行阶段2.5：难度分级，将分级结果追加到本输出末尾，然后附上： 「⏸️ 问题分析 + 难度分级完成（等级：X）。进入阶段3：探索与审查方案，回复「确认」继续。」 [🤖 自动] 自动进入阶段2.5，无需用户确认。
基于阶段2的分析结果，使用规则制判定难度等级，决定后续行为
| 条件 | 判断依据 |
|---|---|
| 根因未知 | 分析后仍无法定位根本原因（知道大概模块但无法定位到具体逻辑） |
| 涉及架构变更 | 需要重构模块间通信、变更设计模式、调整核心数据结构 |
| 涉及数据迁移 | 需要数据库 schema 变更或数据格式迁移 |
| API 协议变更 | 需要修改对外接口签名，影响调用方 |
| 改动范围过大 | 预估改动文件 >10 个 或 预估行数变更 >500 行 |
| 跨仓库/跨服务 | 需要在多个独立 Git 仓库中协同修改 |
| 等级 | 🤖 自动模式 | 👤 手动模式 |
|---|---|---|
| 🟢 容易 | ✅ 正常执行 | 💡 提示「此问题较简单，可切换自动模式」，继续手动流程 |
| 🟡 中等 | ✅ 正常执行 | 💡 提示「此问题风险可控，可切换自动模式」，继续手动流程 |
| 🟠 困难 | ✅ 执行，阶段5完成后暂停等用户审查代码再提交 | ✅ 正常手动流程 |
| 🔴 极难 | ❌ 终止，输出标记报告 | ⚠️ 风险提示，用户选择 A/B |
难度等级（🟢/🟡/🟠/🔴）、命中条件列表、行为提示（终止报告/风险选项 A-B/建议切换模式）、后续行动建议。分级结果保存到 .jira-fix/{JIRA-ID}/02-grade.md，更新 state.json "grade" 字段
[👤 手动] 非极难时：分级结果已追加到阶段2输出，不再单独停顿，直接由阶段2出口的 ⏸️ 统一等待用户确认。 [👤 手动] 极难选 B（继续）时，附上：「⚠️ 已知晓高风险，进入阶段3：探索与审查方案，回复「确认」继续，或回复「A」终止。」 [🤖 自动] 自动进入阶段3，无需用户确认。
🔌 增强能力集成：若环境探索发现了「💡 方案设计」类能力（如 brainstorming、OMC analyst/architect agent 等），在方案探索环节加载并辅助多方案对比分析。未发现则按下述原有流程执行。
自动生成 2-3 个方案，优先选：更彻底解决 > 符合规范最佳实践 > 改善代码质量 > 改动较少。
若缺少选型偏好，先提出 1 个最关键的问题，得到回答后再输出方案对比与推荐。
| 方案 | 描述 | 优点 | 缺点 | 复杂度 | 推荐度 |
|---|---|---|---|---|---|
| 方案1 | ... | ... | ... | 低/中/高 | ⭐⭐⭐⭐⭐ |
| 方案2 | ... | ... | ... | 低/中/高 | ⭐⭐⭐ |
[🤖 自动] 自动选定最优方案后进入审查；[👤 手动] 等用户选定后进入审查。保存到 .jira-fix/{JIRA-ID}/03-options.md
⛔ [手动模式 — 阶段3 方案选择出口] 输出方案对比表后立即停止，在表末必须附上： 「请选择一个方案（回复方案编号，如「方案1」），AI 将进入方案审查。」 🤖 [自动模式] 自动选定最优方案，直接进入审查。
对选定方案深度核查，循环审查直到通过；工具限制：✅ Read；❌ Edit/Write/Bash
| 结论 | 判定标准 | 后续动作 |
|---|---|---|
| ✅ 通过 | 四项审查维度均无阻断问题，仅存在可接受的低风险 | 进入阶段4 |
| ❌ 不通过 | 任一维度存在需解决的问题或不可接受的风险 | 进入优化→重新审查循环 |
阻断问题判定指引（满足任一即为 ❌ 不通过）：
非阻断问题（可标注为建议，但不阻止通过）：
方案选定 → 审查（第 N 轮）→ 输出审查报告
↓
审查结论判定
├── ✅ 通过 → 进入阶段4
└── ❌ 不通过 → 方案优化 → 回到审查（第 N+1 轮）
↓
达到循环上限？
├── 否 → 继续循环
└── 是 → 超限处理
每轮审查必须输出：
保存到 .jira-fix/{JIRA-ID}/03-options.md（追加审查记录）
⛔ [手动模式 — 阶段3 审查出口] 输出审查报告后立即停止，在报告末必须附上： 「⏸️ 方案审查完成。是否进入阶段4：制定计划？回复「确认」继续，或说「修改方案」重新审查。」 🤖 [自动模式] AI 自动判定通过/不通过；通过进入阶段4，不通过自动优化后重审（上限3轮，超限暂停）。
详细可执行的修改计划
🔌 增强能力集成：若环境探索发现了「📝 计划制定」类能力（如 writing-plans、OMC planner agent 等），加载并辅助生成更结构化的执行计划。未发现则按下述原有流程执行。
计划必须包含：① 根因回顾 ② 方案回顾 ③ 架构设计（可选 Mermaid）④ 文件修改清单（表格：文件/内容/类型）⑤ 修改顺序（考虑依赖关系）⑥ 测试场景（Web/Mobile/兼容性）⑦ 影响范围（服务层/Web/Mobile/风险等级）⑧ 回滚方案
| 场景 | 行为 |
|---|---|
| [🤖 自动] 普通情况 | 自动确认，立即进入阶段5 |
| [🤖 自动] 难度🟠困难 或 方案风险>中 | 输出计划后暂停，等用户确认后继续 |
| [👤 手动] 普通情况 | 等用户确认 |
| [👤 手动] 极难选B | 强制要求用户二次确认「我已知晓风险，继续执行」后才进阶段5 |
保存到 .jira-fix/{JIRA-ID}/04-plan.md
⛔ [手动模式 — 阶段4 出口] 输出计划后立即停止，在计划末必须附上： 「⏸️ 阶段4（制定计划）完成。是否进入阶段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
#，HTML 用 <!-- -->，SQL 用 --）ReadLints 检查，新引入的错误必须修复tsconfig.json 时自动调用 typescript-check skill，新引入类型错误必须修复多项目代码修改：根据文件路径前缀定位对应项目，各项目独立检查 Linter，记录每个项目修改文件及行数统计。
报告生成：执行完成后自动生成 reports/[JIRA-ID]-analysis.md，包含：基本信息、问题分析、根因、解决方案、修改文件清单、遇到的问题、测试建议。
| 场景 | 行为 |
|---|---|
| [🤖 自动] 普通情况 | 自动进入阶段6：检查验证 |
| [🤖 自动] 难度🟠困难 | 暂停，输出执行摘要，等用户审查代码后确认继续 |
| [👤 手动] 普通情况 | 等用户确认后进入阶段6：检查验证 |
| [👤 手动] 极难选B | 暂停，等用户审查代码，不自动提交 |
执行完成后必须输出：已修改文件及关键改动说明、偏离计划的调整（如有需说明原因）、验证要点/自查清单。保存到 .jira-fix/{JIRA-ID}/05-execution.md
⛔ [手动模式 — 阶段5 出口] 输出执行报告后立即停止，在报告末必须附上： 「⏸️ 阶段5（执行计划）完成，请审查代码。是否进入阶段6：检查验证？回复「确认」继续，或告知需要调整。」 🤖 [自动模式] 普通情况自动进入阶段6：检查验证；困难等级时暂停等用户审查代码后确认。
// fix [JIRA-ID] 注释，导致修复点无法追踪原则：只输出检查结果，不修改代码；若验证未达标，按失败类型决定返回路径
🔌 增强能力集成：若发现「✅ 完成验证」类能力（如 verification-before-completion、OMC verifier agent），在验证环节调用（运行测试、确认修复、检查回归），有证据再提交。
npm test、pytest、go test 等），将结果纳入结论| 结论 | 判定标准 | 后续动作 |
|---|---|---|
| ✅ 通过 | 问题已修复，测试通过，无新副作用 | 进入阶段7：提交 PR |
| ❌ 未达标 | 问题仍存在、新副作用未解决或测试失败 | 按失败类型决定返回路径 |
未达标返回路径：
| 失败类型 | 返回阶段 |
|---|---|
| 代码实现有误（方向正确但执行有缺陷） | 阶段5 重新执行 |
| 方案设计有缺陷（测试暴露更深层问题） | 阶段3 重新审查/选方案 |
| 根因分析不完整（问题范围比预期更大） | 阶段2 补充分析 |
【验证结果】
- Jira 复现步骤验证：（逐项列出 ✅ 已修复 / ❌ 仍存在）
- 与阶段4计划对比：已完成 ... / 未完成 ...（如有）
- 测试结论：（已运行 → 附结果；无自动化测试 → 列手动验证要点）
- 副作用检查：Linter ✅/❌，TS ✅/❌，功能副作用 ✅/❌
- 逻辑完整性：...
- 验证结论：✅ 通过 / ❌ 未达标（未达标需说明返回路径及原因）
保存到 .jira-fix/{JIRA-ID}/06-verification.md，更新 state.json。
工具限制：✅ Bash（仅运行测试命令）；❌ Edit/Write
⛔ [手动模式 — 阶段6 出口] 输出验证结果后立即停止，在结果末必须附上：
- [✅ 通过]：「⏸️ 阶段6（检查验证）通过。是否进入阶段7：提交 PR？回复「确认」继续。」
- [❌ 未达标]：「⏸️ 验证未通过。建议返回 阶段X（原因：...）。回复「确认」同意返回，或指定其他处理方式。」 🤖 [自动模式] AI 自动判定通过/未达标；通过进入阶段7；未达标按返回路径自动回退（上限 2 次，超限暂停）。
🔌 增强能力集成：
verification-before-completion、OMC verifier agent），在提交前执行独立验证（运行测试、确认修复、检查回归），有证据再提交requesting-code-review、OMC code-reviewer agent），提交后自动发起代码审查git-commit SKILL（execute=true，自动模式）：自动 add / commit / pushgit remote -v 判断平台（URL 含 github.com → gh pr create；含 gitlab → glab mr create），标题格式与 commit message 保持一致；描述必须包含根因、修复方案、修改文件清单、验证场景（功能/边界/回归各 ≥2）、Jira 链接jira_get_transitions + jira_transition_issue 流转状态，再独立调用 jira_add_comment(issue_key=..., body=...) 写修复评论。⚠️ 禁止通过 jira_transition_issue 的 comment 参数传评论——该参数不可靠，评论可能被静默丢弃；jira_add_comment 的评论内容参数名为 body（非 comment）。流转到「已修复」；禁止流转到"关闭"或"验证通过"（QA 操作）；无匹配时跳过记警告修复评论字段：修复分支、Commit、根因、修复方案、修改文件、分析报告路径、验证场景（功能/边界/回归各 ≥2）。
收集提交信息，展示将要执行的 commit 计划（分支、commit message、修改文件、验证场景各 ≥2 条）和 Jira 回写内容，等用户确认后，AI 执行 add / commit / push + 创建 PR/MR，然后依次：① jira_get_transitions + jira_transition_issue 流转状态；② 独立调用 jira_add_comment(issue_key=..., body=...) 写修复评论（⚠️ 禁止通过 transition 的 comment 参数传评论；body 是评论内容的正确参数名）。修复评论字段同自动模式。
⛔ [手动模式 — 阶段7 出口] 展示提交计划和验证场景后立即停止，在末尾必须附上： 「⏸️ 提交计划已就绪。确认后 AI 将执行 push + 创建 PR/MR + Jira 状态回写。回复「确认」继续，或告知需要修改。」 🤖 [自动模式] 无需确认，自动执行 push + 创建 PR/MR + Jira 状态回写（仅流转到「已修复」，禁止流转「关闭」或「验证通过」）。
<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、推送状态、PR/MR URL、Jira 回写状态、分析报告路径；多项目时用表格。错误处理：回写失败不阻断流程，仅输出警告并记录到报告。
保存到 .jira-fix/{JIRA-ID}/07-report.md
jira_transition_issue 的 comment 参数传评论（该参数不可靠，必须独立调用 jira_add_comment）PR/MR 已在阶段7创建，等待 CI + Code Review，完成合并、分支清理与主分支同步
🔌 增强能力集成：若发现「📋 代码审查」类能力（如 requesting-code-review、OMC code-reviewer agent），可辅助推进正式 Code Review 流程。
gh pr merge --merge；GitLab glab mr merge（参数与团队策略一致）git push origin --delete fix/jira-fix-[JIRA-ID]git checkout main && git pull origin main（将 main 换成本仓库默认分支名）git branch -d fix/jira-fix-[JIRA-ID]07-report.md）和描述摘要，立即停止，等用户完成 Code Review 并确认合并gh pr merge --merge；GitLab glab mr merge（参数与团队策略一致）git checkout main && git pull origin main，main 换成本仓库默认分支名）⛔ [手动模式 — 阶段8 出口] 展示 PR/MR URL 后立即停止，在末尾必须附上： 「⏸️ PR/MR 已在阶段7创建，请完成 Code Review。是否合并并清理分支？回复「确认」继续。」 🤖 [自动模式] CI 通过后自动合并，执行分支清理与主分支同步，无需用户干预。
合并状态、分支清理状态（本地/远程）、主分支同步状态（PR/MR URL 已在阶段7 07-report.md 中记录）。保存到 .jira-fix/{JIRA-ID}/08-merge.md，同时更新 state.json current_phase: "completed"。
gh pr merge、glab mr merge 等平台合并命令--admin 或 --force）修改前自动 stash；警告阈值：>10文件 或 >500行；阻断阈值：>20文件 或 >1000行（需 --force 解除）；Linter 错误自动阻断；审查循环上限：3 轮（超限暂停或标记跳过）；记录所有自动决策日志。
| 错误 | 后果 | 修正 |
|---|---|---|
| [👤 手动] 跳过阶段1.5直接进入阶段2分析 | 带着错误理解进入技术分析，后续工作全部偏向 | 手动模式必须先完成理解对齐并获用户确认 |
| [👤 手动] 阶段1.5中读取代码库 | 破坏只读+禁探索约束，混淆理解对齐与技术分析 | 阶段1.5严格仅基于 Jira 数据，禁止任何代码探索 |
| 跳过存在性验证直接分析根因 | 分析不存在的问题、浪费上下文 | 阶段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 修改代码 | 破坏只读约束 | 见「阶段工具约束」表 |
| 跳过检查验证直接进入阶段7提交 | 提交未经验证的修复，PR 内藏 Bug | 阶段5完成后必须先经阶段6检查验证 |
| 检查验证阶段修改代码 | 破坏只读约束 | 阶段6只允许运行测试命令，禁止 Edit/Write |
| 测试失败仍判定通过推进提交 | 已知问题带入 PR | 测试失败必须返回修复，不可强行通过 |
| [🤖 自动] 验证未达标回退超过 2 次不暂停 | 无限循环浪费资源 | 超过 2 次回退必须暂停等用户介入 |
通过 jira_transition_issue 的 comment 参数传评论而非独立调用 jira_add_comment | 评论被静默丢弃，Jira 上无修复记录 | 独立调用 jira_add_comment，transition 的 comment 参数不可靠 |
批量修复场景请使用 jira-fix-batch skill。