Bugfix Workflow

---
name: bugfix-workflow
description: 缺陷修复纪律工作流（Bugfix，产物定位 + A/B/C 根因分层模型）。当用户报告已交付/已有代码有 bug（修复缺陷/XX 坏了/功能不对/报错/出参入参不对/URL 调不通）时加载本 skill：先记录用户原话 → 前置分类（产品口径型先对齐）→ 把问题定位到中间产物（1.1 功能项 → 3.x 方案/验收场景/接口清单）→ **A/B/C 根因分层判定**（A 实现偏离产物→只改代码；B 产物逻辑错→先轻量修 3.x，再改代码对齐；C 需求口径变→不是 bug，停止转需求变更）→ 最小修复（全量注释/日志）→ 功能回归 → /check-standards 兜底 → 修复单（含产物同步记录）+ 经验。触发场景：修 bug、修复缺陷、XX 坏了、功能不对、接口报错、参数不对。WHEN NOT：新功能/完整模块 → ai-dev-workflow；纯生成/修改业务代码（非缺陷）→ java-code-standards + comment-standards。边界：修复涉及需求/范围变更（C 层）→ 停止本流程转 ai-dev-workflow（0.8/需求变更）；该模块 docs/ 已有 ai-dev-workflow 历史产物 → 按本流程"产物定位 + 轻量产物同步"处理，产物同步不豁免。
---

# Bugfix Workflow（缺陷修复纪律 · 产物定位 + A/B/C 根因分层）

**定位**：修 bug 也要有纪律——**先定位到中间产物、判断根因在哪一层，再决定"改产物 / 改代码 / 都不是"**，禁止盲试，禁止修一个 bug 引发新问题。

## 为什么：bug 藏在三层里的某一层

```
① 需求口径层   用户期望（接口/行为应该是什么）          → 变更，不是 bug
② 设计逻辑层   3.x 方案：核心逻辑 / 验收场景 / 接口清单   → bug 可能在这（产物错）
③ 实现编码层   代码是否按 ② 写对                        → bug 也可能在这（实现错）
```

关键认知：**先修中间产物再改代码，只对 ② 层成立**；若 ② 是对的而代码写错，改产物反而是污染。

## 与家族其它 skill 的边界

| skill | 边界 |
|---|---|
| ai-dev-workflow | 新功能/完整模块走主流程；**C 层（需求口径变更）→ 停止本流程**，转需求/0.8 处理，不在 bugfix 里改口径 |
| check-standards | 修复完成后加载做兜底核对（注释/日志/规范逐项，附证据） |
| java-code-standards / comment-standards | 改代码按对应规范（命名/分层/注入/日志/事务/注释） |

## 工作流（命令 `/bugfix`，详见 `commands/bugfix.md`）

```
bug 报告（用户原话 / URL / 入参 / 出参 / 报错 / 日志）
  ▼
0. 前置分类：产品口径型 Bug？（涉及行为/权限/可见性/默认值/保存下载规则等）
   ├─ 是 → 先与用户对齐期望口径，再判层（期望是"新口径" → C，转变更）
   └─ 否 → 继续
  ▼
1. 产物定位：把 bug 映射到中间产物
   1.1 功能项 → 3.<n>.1-技术方案（核心逻辑/验收场景）→ 3.<n>.2-接口清单（入参/出参/错误码）
   —— 用产物当"定位地图"，别直接翻代码猜
  ▼
2. A/B/C 根因分层判定（对照产物，判断错在哪层）：
   A 实现偏离产物   产物对，代码没按它写
   B 产物逻辑错     产物本身与真实期望不符（代码按产物写了但产物就错）
   C 需求口径变了   给的是新期望，产物/代码没错
  ▼
3. 按层修复：
   A → 按产物修正代码（产物不动）
   B → 先轻量修 3.x（逻辑/验收场景/接口清单对应段）→ 再改代码对齐
       （产物与代码同源对齐；改动登记修复单"产物同步记录"）
   C → 停止本流程，转 ai-dev-workflow（需求变更 / 0.8），不在 bugfix 里改
   ▼
4. 最小修复：只改根因相关；本次代码全量注释 + 方法级日志
   ▼
5. verify：相关功能回归 + 受影响验收场景抽查，附证据
  ▼
6. 兜底与沉淀：/check-standards 核对 → 修复单落盘
   docs/<模块>/bugfix-<YYYYMMDDHHMMSS>.md（含产物同步记录）
   → 经验记入 docs/experience.md（跨模块通用标 [HARD]）
```

## A/B/C 分层判定速查

| 层 | 判定（对照产物） | 修复动作 | 产物是否改动 |
|---|---|---|---|
| A | 3.x 逻辑/验收场景/接口清单是对的，代码没按它写 | 按产物改代码 | ❌ 不改 |
| B | 3.x 逻辑/验收场景/接口清单口径本身与真实期望不符 | 先改 3.x 对应段 → 代码对齐 | ✅ 轻量修正并登记 |
| C | 用户期望变了（新需求） | 停止 bugfix，转 ai-dev-workflow | 走变更流程 |

## 产物定位对照（用中间产物找问题）

| 问题信号 | 先看产物 | 重点看 |
|---|---|---|
| 接口 URL 调不通 / 404/405 | 3.<n>.2-接口清单 | 路径/方法/参数是否与实现一致 |
| 入参报错 / 校验不对 | 3.<n>.2 + Controller 方案 | 参数定义、校验规则、DTO 结构 |
| 出参字段不对 / 缺字段 | 3.<n>.2 + 3.<n>.1 逻辑 | VO 结构、组装逻辑、是否该返回 |
| 状态/计算结果不对 | 3.<n>.1 技术方案 | 核心逻辑、验收场景预期 |
| 边界/异常场景炸 | 3.<n>.1 技术方案 | 验收场景三态（合法/非法/边界）是否缺漏 |

## 轻量产物同步规则（B 层专用，不走整套 0.8）

- B 层**只改该 bug 涉及的 3.x 相应段落**（核心逻辑 / 验收场景 / 接口清单对应行），不做无关产物重构；
- 涉及验收场景/接口清单口径的改动，**先改产物对应段 → 再改代码对齐**（不再要求先写测试）；
- 产物改动逐条登记在修复单「产物同步记录」：`旧表述 → 新表述 + 原因 + 联动文件`；
- 该模块其它产物若引用被改段落（如 1.1 功能清单依赖关系、4.1 任务），同步检查并标注引用是否受影响；
- **A 层禁止为"显得规范"而改正确产物；C 层禁止拿新需求当 bug 修。**

## 硬性要求

- 先记录用户原话，再转工程问题（禁止 AI 一开始就改写用户问题）
- 先复现、先产物定位、先分层判定，后动手；根因不清禁止改码
- 最小修复：只改根因相关，禁止"顺手优化"/重构/无关清理
- 不改需求口径（C 层转变更路径）；修复失败 ≥3 次自动修复循环 → 停下问用户
- 注释与日志不豁免：本次修改/新增代码全量注释 + 方法级日志
- 修复后必须有功能回归证据，`/check-standards` 兜底后才算完成（如需运行时行为验证，可显式用 `test-workflow`（`/gen-test`）生成验收测试工具）

## 产物

- 修复单：`docs/<模块>/bugfix-<YYYYMMDDHHMMSS>.md`（模板 `templates/bugfix-修复单.md`），含 **A/B/C 判定 + 产物同步记录**
- 代码改动（最小）+ 功能回归证据 + 核对结论

## 完成标准

- [ ] 用户原话已保留，产品口径型已前置分类（是 → 已与用户对齐）
- [ ] bug 已复现；已**产物定位**（映射到 1.1 → 3.x.1 → 3.x.2）
- [ ] **A/B/C 判定**明确并写进修复单（C → 已停止并转变更路径）
- [ ] A：只改代码、产物未动；B：3.x 对应段已轻量修正 + 登记产物同步记录 + 代码已对齐；C：已转 ai-dev-workflow
- [ ] 修复为最小改动；本次代码全量注释 + 方法级日志
- [ ] 相关功能回归证据（受影响验收场景抽查）
- [ ] `/check-standards` 兜底核对完成
- [ ] 修复单已落盘，经验按需写入 `docs/experience.md`