jira-fix-workflow

Jira Bug-Fix 工作流

Jira 端到端 Bug 修复流程；阶段 1–6 为只读。手动模式（默认）要求在各阶段之间进行确认。

前提条件：PAT/认证遵循 jira-read 凭据约定（环境变量 JIRA_PERSONAL_TOKEN、别名 JIRA_PAT，或 ~/.config/jira-certs/jira-pat.txt）；mcp-atlassian 为可选项。Git 环境运行正常。 格式参考：输出模板、状态目录、提交格式和退出脚本见 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，从阶段 3重新分析
"从上次继续", "恢复修复 [URL]", jira-fix [URL] --resume	当前模式	从上一个检查点继续
"ai-proxy 模式", "AI 代理模式", "切换 ai-proxy"	overlay	自动载体；根据 ai-proxy-discipline 先进行轻量冻结，再进入占用状态

模式检测：overlay 触发词（「ai-proxy 模式」「AI 代理模式」「切换 ai-proxy」 / "ai-proxy mode" / "switch to ai-proxy"）根据 workflow-mode-lifecycle 请求 overlay——如果自动和 overlay 同时出现，则以 overlay+冻结为准。否则，包含 "自动" / --auto → 自动；包含 "强制" / "跳过分级" → 跳过评级（自动）；包含 "继续修复" / "再次修复" / --retry → 从阶段 3 重新进入；包含 "从上次继续" / "恢复" / --resume → 从检查点恢复；否则为手动。

无人值守代理退出

当本次运行约定或任务卡记录了 Stage-exit policy: ai-proxy（自动载体；队列子项足够，但非必需）时，每个手动停止点都会根据 ai-proxy-discipline 成为代理检查点。轻量冻结（口头触发 ≠ 占用）在此处进行。合并、不可逆操作、受保护分支和 Jira 回写仍仅限人工处理（暂存并创建工单）。其他任何策略值或未设置 → 保持当前的非代理行为。

停止点预测：如果本次运行开始时已有冻结约定（含问题和冻结决策的队列子项，或已写入的独立轻量冻结），则在分析前先输出预测表——列出每个手动退出点，并标明由冻结决策覆盖或将创建新工单。如果在运行中途请求 overlay，则在轻量冻结后输出剩余退出点的预测，然后继续当前阶段（不要从分析阶段重新开始）。

强依赖和前提条件检查

强依赖项列在 frontmatter 的 dependencies 中。阶段 0 通过后、阶段 1 开始前，扫描可用的技能；如果有任何缺失 → 输出结构化通知并立即中止（格式见 solve-workflow/reference.md）。不得降级处理。

模式生命周期

核心规则位于 workflow-mode-lifecycle 中。“完整流程完成”表示阶段 0–10 均正常结束（包括任何阶段的最终终止）；失败中止 / 🔴 极难问题终止 / 用户停止 / 达到审查上限后介入并终止，都会恢复为手动模式。重新进入自动模式需要明确触发；隐式继续（“继续修复”“再改一下”）不会重新激活自动模式。

工作流特有差异：阶段 9 完成 / 阶段 10 合并完成 / 🔴 极难问题终止（自动） → 恢复为手动模式；阶段 8 未达阈值的回滚保留当前模式（自动，最多回滚 2 次）；--retry → 重置为手动模式；--resume → 保留检查点的模式。

队列子任务模式（goal-driven-queue 调度）

由 goal-driven-queue 调度时（调用中明确带有 queue-child 上下文标志——绝不根据环境信号猜测），此流程会相应调整：卡片的目标条件中包含 Jira 问题链接；其冻结决策块提供阶段 0–1 的信息；Stage-exit policy 随流程传递（占用情况由上方的 Unattended 指针决定，并非此标志独有）；开场时提供停止点预测（每个手动退出点 × 是否已由冻结决策覆盖，还是会新建工单）。终点为 PR-open：阶段 9 后停止，仅记录收尾情况——阶段 10（合并 + Jira 回写）延后由人工处理（合并权限和外部跟踪器回写绝不代为执行）；队列的验收包会将其列为待跟进事项。独立使用时（不带标志）：叠加层/占用情况仍遵循 Stage-exit policy 和 Unattended 指针；PR-open 终点不适用；收尾仍按此技能的阶段 9–10 执行（叠加层不会未经人工介入就自动完成合并/回写）。本次运行作为队列子任务时，完成报告须包含问题、原因、已完成的修复，以及证据列表。每项证据都必须是已打开的 UI 检查，并引用 png、jpg、jpeg 或 webp 路径；或者是非 UI 检查，并注明命令和简短的输出摘要。缺失或空白的图像视为待处理，并注明仍需截图。不得编造图像。在用已打开的 UI 图像作为检查依据之前，须按照 completion-evidence-discipline 检查图像。本次运行不会编写 HTML 页面，也不会编写证据 HTML。

⚡ 快速参考（执行前阅读）

阶段	编辑/写入	Bash	👤 手动停止点	🤖 自动停止点	必需输出
0 前置条件检查	❌	✅（worktree gate）	失败则中止；成功→1	失败/P0 则中止；成功则继续	检查摘要
1 读取 Jira	❌	❌	→2	→2	Jira 摘要
2 理解对齐	❌	❌	⛔ 等待确认→3	跳过→3	复述 + 歧义
3 分析	❌	❌	存在性检查失败则停止；完成→4，然后 ⏸️→5	存在性检查失败则停止；完成后继续	根本原因 + 难度
4 评级	❌	❌	🔴⛔ 展示 A/B；否则无需单独停止	🔴⛔ 终止；否则继续	难度等级
5 方案审查	❌	❌	⛔ 选择方案；审查后 ⛔	审查超过 3 轮则 ⛔	方案表 + 审查结果
6 计划	❌	❌	⛔ 等待确认	高难度/高风险时 ⛔	变更清单
7 执行	✅	✅	⛔ 等待审查；多仓库时先确认分支	高难度时 ⛔ 等待审查	执行报告
8 验证	❌	✅ 测试	⛔ 等待确认	通过→9；未达阈值则回滚，最多 2 次	验证结果
9 提交	❌	✅ git/CLI	⛔ 确认后推送 + 创建 PR	自动推送 + 创建 PR	完成报告 + URL
10 合并	❌	✅ 合并/可选覆盖率检查	⛔ 确认后合并	⛔ 同上，必须确认	合并/清理/Jira 报告

阶段 7：先创建分支；在构建/lint/tsc 前调用 node-version-discipline。阶段 10 的 C 部分会根据偏好/询问结果决定是否运行覆盖率分析器。

各阶段自动/手动差异：reference.md § 模式差异快速参考。

通用原则

• 先调查，再发言：没有代码证据，不下结论
• 主动提问：遵循 clarifying-question-discipline（每轮只问一个问题；多轮沟通直到明确；先澄清，不要急于作答）。涉及领域术语时，还须遵循 domain-language-discipline。
• Jira 状态边界：工程团队只将问题状态变更为“已修复”（Fixed）；关闭问题/标记为已验证由 QA 负责

路径选择

在阶段 4 评分后选择；可以升级，不能降级。

路径	适用情况	要求
Lean	🟢 简单	1 个解决方案 + 一条风险说明即可；计划可合并；不得跳过阶段 8/9
Standard	🟡 中等	完整执行阶段 1-10
Full	🟠 困难 / 🔴 极难（选择 B）	执行所有阶段；阶段 7 后暂停等待审核

手动模式下升级需要用户确认。

状态持久化（中断恢复）

恢复：存在 state.json 时，🤖 自动从 current_phase 继续；👤 手动模式会询问是否恢复。如果本次运行有 context-budget-discipline 的账本，则根据账本及其引用的工件重建状态，而不是重放历史记录。清理：完成时将 current_phase 设为 "completed"。目录布局和架构：reference.md § 状态目录和 state.json。

--retry（重新进入阶段 3）：跳过 0/1；读取现有的 01-jira-info.md；询问一次“上次修复了什么 / 新症状是什么”；将“本次迭代的上下文”写入 02-analysis.md；重置状态（current_phase: 3、completed_phases: [0,1]，清除 grade/selected_option/review_*）；在分支名称后追加 -v2/-v3…；如果根本原因仍不明确，优先采用插桩调试。

---

阶段 0：前置条件检查

任何一项失败都会中止流程。

1. 检测模式（包括 --force / --resume / overlay）。Overlay 会触发请求轻量冻结，然后按 ai-proxy-discipline 占用资源。在首次持久化写入（state.json、文档或代码）之前，加载 git-worktree-discipline（worktree 门禁 + 可选隔离）；然后将模式写入 state.json
2. 按 jira-read 解析凭据（不得仅因缺少 mcp-atlassian 而中止）。如果存在 MCP jira_get_issue 工具，优先使用它检查连接；如果不存在，则降级使用本地 jira-read 缓存。仅当完全无法获取问题数据时才中止。
3. P0 拦截（仅自动模式）：P0 → 中止，切换到手动模式
4. Git：🤖 工作区有改动→stash；👤 工作区有改动→提示如何处理

输出：reference.md § 阶段 0。成功后直接进入阶段 1。

---

阶段 1：读取 Jira 信息

完成 jira-read 凭据链检查后，调用 jira-read {JIRA-ID} --live（降级至缓存 → 再进一步降级为手动模式/中止）。保存为 01-jira-info.md。提取：ID、标题、优先级、状态、描述、复现步骤、预期结果/实际结果、附件、评论。输出：reference.md § 阶段 1。工具：✅ mcp / jira-read；❌ Edit/Write/Bash。直接进入阶段 2。

性能领域问题（缓慢 / 卡顿 / 资源增长）：按照 perf-optimize-workflow 的证据门控范式执行分析、优化和验证工作（基准测试基线 → 证据门控 → 单目标迭代 → A/B 结论），并将结论整合回本工作流的各阶段；Jira 编排（分支、MR、回写）仍在此处进行。注意：其优化活动会在仓库中为每个项目创建工件（基准测试日志 + 测试框架，以及预置的 code-insight/code-optimizer skills）——请将它们与修复一并提交；优化-验证循环还需要环境循环运行器（分析阶段始终执行）。仅供参考，不是依赖项。

---

阶段 2：理解对齐

重述阶段 1 得出的理解并指出模糊之处；禁止阅读代码。🤖 跳过→3。👤 必须先确认才能进入→3。

输出：问题重述（不作技术判断）/ 关键要素 / 模糊之处（每轮只问一个问题）/ 范围拆分（如适用，仍不得探索代码）。格式：reference.md § 阶段 2；保存为 02-alignment.md。

---

阶段 3：分析问题

加载 analysis-core §§1-3；阶段输出必须以分析门控输出块收尾（analysis-core §5——红色循环／调试入口／场景补充／临时变更；缺少此块会阻止进入阶段 4）。映射：{next-stage} = 阶段 4「难度评级」；{root-cause step} = 根因分析；{impact-assessment step} = 影响范围；{upstream-eval step} = 上游依赖修复评估。当预期结果是用户可见或可操作的结果时，同一次加载会按照 analysis-core 的要求运行 competitive-research。不要复述其方法。

工作流特有差异：① 行业普遍问题评估是一个门控；② 🚫 没有可行的修复方案 → 报告 + 停止，不进入阶段 5 + 撰写 Jira 评论（加载 jira-wiki-markup；模板见 reference.md）；③ 存在性检查 ❌ → 停止 + 撰写 Jira 评论（加载 jira-wiki-markup）+ 等待用户；④ 产物 02-analysis.md（包含难度预评估）。

👤 直接继续进入阶段 4，将评级附加到输出末尾，然后 ⏸️ 暂停并等待确认后再进入 →5。🤖 → 阶段 4。

---

阶段 4：难度评级 + 模式决策网关

🔴 极难（符合任意一项即可）

根因未知 | 架构变更 | 数据迁移 | API 协议变更 | 预计文件数 >10 或代码行数 >500 | 跨仓库／跨服务

其他评级

文件数 ≤3 且根因明确 → 🟢；4-10 个且基本明确 → 🟡；≤10 个但不太明确、变更较大 → 🟠

模式 × 评级

评级	🤖	👤
🟢/🟡	正常执行	可建议切换为自动模式；继续手动执行
🟠	阶段 7 后暂停审核	正常手动执行
🔴	终止 + 标记报告	风险提示，选择 A/B

将评级写入 04-grade.md 并注明 grade；声明路径。模板：reference.md § 阶段 4。👤 对非极难情况不必单独停止；🔴 选择 B 的话术见 reference.md。🤖 非极难 →5。

---

阶段 5：探索并审核解决方案

如果思路仍不清晰，在解决方案表之前遵循 decision-fog-discipline。提供 2-3 个解决方案（YAGNI）。🤖 自动选择（优先级：全面性 > 最佳实践 > 代码质量 > 最小改动）→ 审核。👤 如果用户未表达偏好，只询问一次，然后展示对比表。

架构边界预检（决策顺序）：当候选解决方案跨越进程或层级边界时，先回答预检问题，再权衡短期成本（改动规模／复用／单仓库）——（1）运行时初始化位置：被调用的能力由哪个进程／层级初始化；（2）边界合法性：跨层导入是否会将被调用方的依赖树带入调用方的打包图（打包器的静态预扫描会使动态 require/import 无法作为规避方案）；（3）归属分类：系统能力 vs 数据／产品能力 vs 调用层的定位。边界判定结果随对比表呈现，并作为自动模式选择的门控。方法论：code-design-review Layer A 依赖方向维度。单层解决方案不触发此预检。

输出：列表 → 展开详情 → 一张对比表（见 reference.md § 阶段 5 解决方案对比）→ 03-options.md。👤 在对比表之后停止。

审核：加载 staged-review-flow。映射：{next-stage} = 阶段 6；{artifact-sink} = 03-options.md；{extra-dimensions} = 无；{batch-overcap-behavior} = 标记为“审核失败（超上限）”，并转到下一个问题。✅ 读取；❌ 编辑／写入／Bash。

---

阶段 6：制定计划

必须包含：根因／解决方案回顾、架构（可选 Mermaid）、文件变更表、执行顺序、测试场景、影响范围、回滚方案。保存为 04-plan.md。

场景	行为
🤖 正常	自动进入阶段 7
🤖 🟠 或风险 > medium	暂停并请求确认
👤 正常	等待确认
👤 🔴 选择 B	需要二次确认：“我了解风险，继续”

退出脚本：reference.md。

---

阶段 7：执行计划

修改生产环境代码前，遵循 design-approval-gate（手动：用户通过；自动／强制：注明豁免理由并留痕）。

上下文预算：根据 context-budget-discipline 评估阶段边界重置和压缩阈值（账本路径来自阶段 6 计划／卡片补充）；任何重置前都必须先填写完整的账本条目。

**Figma 像素保真度：**当目标、卡片、问题或计划文本包含 figma.com 或 node-id=，或者用户要求像素级还原时，加载 figma-pixel-implement 并遵循其要求。这些子串即为范围事实。将这些行设为硬性要求；不要因任务也会检查行为而将它们归入软性要求或人工检查。探测可见文本、可见性标记或列表长度，均不能通过像素级行的检查。当同一文本还包含 参考、match the existing 或 same as 时，将此事实传递给 verify，以便将指定控件的交互状态列为检查项。若目标代码仓库中没有持久化的清单和规格文件路径，则 Implement 尚未完成。该技能会在同一次运行中继续执行 figma-pixel-verify，直到总体结果为 PASS 或测量命令无法运行。此处不要复述其方法。

分支：命名和单／多仓库流程见 reference.md § 阶段 7 分支创建详情；写入 00-branch.md。

严格按照计划执行；逐项完成后勾选 TodoWrite／计划复选框。为每项变更添加标记 // fix [JIRA-ID]。质量门禁：node-version-discipline → ReadLints → 存在 tsconfig 时执行 typescript-check。🤖 多仓库变更和 lint 按仓库分别执行，并写入 reports/[JIRA-ID]-analysis.md。

执行后：🤖 正常→8，🟠 暂停并等待审查；👤 正常则等待确认后→8，🔴 选择 B 则暂停，不自动提交。报告写入 05-execution.md。对于行为变更，遵循 test-first-discipline；业务逻辑缺少测试时，调用 test-suite-ensure（mode=advisory）——test-suite-ensure 不能替代 test-first。退出脚本：reference.md。

---

阶段 8：检查与验证

仅输出结果——不要更改代码。上下文预算：发生上下文重置时，依据台账和工件进行验证（遵循 context-budget-discipline）；绝不重放之前会话的历史。对照 Jira 复现步骤／预期结果、阶段 6 的计划、测试、副作用和根本原因进行比较；使用 analysis-core §4 中的调试验证循环。验证执行遵循 runtime-verification-discipline（AI 在环境中自行执行验证；只有在确认存在真正的硬性限制时才将步骤交给用户，并说明原因）。当目标、卡片、问题或计划包含 figma.com 或 node-id=，或者本次运行是基于 Figma 实现的，加载 figma-pixel-verify 并遵循其要求；缺少测量报告（常驻工件中的 Verify 部分，或 Spec 源文件的同级文件）会阻止此验证阶段通过。Spec 差异 FAIL 不算通过验证——重新进入 figma-pixel-implement，补全表格。即使本次运行未进行实现，只要需要检查视觉对齐，也要加载该技能。只有当该报告的总体状态为 PASS（包括已接受的残余项），且其通道为已布局的测量环境（storybook、isolated-harness、preview、full-app 或 layout-probe）时，此阶段才算通过。任何其他结果都表示此阶段失败，并返回实现阶段，继续修复／重新测量循环。此阶段还会对该报告运行 figma-pixel-verify 技能中的 scripts/check-figma-verify-report.mjs；退出码非零则阶段失败。验证报告须如实填写，遵循 staged-review-flow 和 completion-evidence-discipline。模板：reference.md § Stage 8。

判定	下一步
✅	→9
❌	实现错误→7；方案缺陷→5；根本原因分析不完整→3

🤖 结果低于阈值时自动回滚，最多 2 次，然后暂停。👤 等待“通过”／“返回修复”／“重选方案”。保存为 06-verification.md。

---

阶段 9：提交 PR/MR

上下文预算：起草报告时读取台账和所引用的工件（遵循 context-budget-discipline），而非完整对话记录。

加载 delivery-discipline 并遵循其要求。提供：

• {commit-context}：type／scope／subject／jira_id（消息格式见 reference.md § Commit Message Format——必须包含 Jira ID）
• {pr-body-extra}：根本原因、解决方案、文件、验证场景（功能／边界／回归场景各至少 2 个）以及 Jira 链接

👤 展示交付计划后暂停；确认后由 AI 执行。🤖 直接执行。完成输出：reference.md § Stage 9 → 07-report.md。

---

阶段 10：审查与合并

展示 PR/MR URL（来自阶段 9）。加载 feature-branch-closeout，获取收尾菜单（PR 已打开时，通常包括合并／保留／继续）。自动和手动模式都必须先获得用户确认，才能合并。

选择合并后：

1. feature-branch-closeout 加载 merge-discipline（Part A→B→C→R→D；检查清单见该技能的 reference.md）
2. 合并（gh pr merge --merge／glab mr merge）→ 删除远程修复分支 → 同步默认分支 → 删除本地分支
3. 加载 jira-status-writeback（字段映射：分支、提交、PR URL、根本原因、解决方案、文件、报告、验证场景）；写回失败不阻止完成。直接添加 Jira 评论前，先加载 jira-wiki-markup，再运行 jira_add_comment。

写入 08-merge.md；将状态设为 current_phase: "completed"。

回顾（委托给 learn-and-improve）

阶段 10 收尾后（合并并完成写回，或选择保留／继续），加载 learn-and-improve 并遵循其框架。不要在此处重复说明回顾方法。

---

安全机制（自动模式）

更改前暂存；超过 10 个文件或 500 行时发出警告；超过 20 个文件或 1000 行时阻止操作（需要 --force）；遇到 linter 错误时阻止操作；审查循环最多 3 轮；记录每项自动决策。

---

常见错误

此处仅列出不明显的陷阱。合并 → merge-discipline；回写 → jira-status-writeback；评论中的 Wiki 标记 → jira-wiki-markup；行业范围／上游问题 → known-issue-research / upstream-dependency-debug。阶段正文中已说明的规则不再重复。

错误	修正方法
👤 跳过阶段 2，或在阶段 2 阅读代码	先对齐；阶段 2 仅处理 Jira 信息
存在性检查不匹配仍继续	停止并评论 Jira，等待确认
🤖 在 🔴 时仍执行；未暂停就回滚超过两次；未经确认就合并	遵循阶段 4 的关卡；达到上限时暂停；合并始终需要确认
缺少 // fix [JIRA-ID]	为每项变更添加标记

---

批量修复

使用 jira-fix-queue 技能（轻量 shell：解析 Jira 列表并加入 goal-driven-queue，设置 Engine: jira-fix-workflow；不会循环执行此工作流或进行合并）。