with one click
jira-fix-workflow
// 当用户说「修复这个 bug [URL]」「帮我修复 [URL]」「jira-fix [URL]」「自动修复 [URL]」「强制修复 [URL]」「继续修复」「从上次继续」时触发。适用于从 Jira 链接出发、对单个 bug 进行端到端修复的场景。
// 当用户说「修复这个 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。