---
name: pdlc-fix
description: 全自动 Bug 修复（定位→复现→修复→测试→文档）
argument-hint: <Bug 描述>
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
layer: 1
stage: fix
produces:
  - docs/04_testing/defects/<defect-id>-defect.md
requires: []
next_step: pdlc-ship
terminal_state: fix_done
---

# 全自动 Bug 修复

<!-- @include templates/prompts/iron-law.md -->

接收一句话 Bug 描述，全自动完成定位、复现、修复、测试、文档更新，中途不暂停、不询问用户。

## 执行规则

- **全程自动**：不在任何步骤暂停等待确认，遇到歧义自行做合理假设并在最终报告中说明
- **严格顺序**：必须按阶段一→二→三→四→五顺序执行，不得跳过
- **最小改动原则**：只修复 Bug 本身，不顺手重构或优化不相关代码
- **测试验证才结束**：全量测试通过后才输出最终报告

---

<!-- @include templates/prompts/defect-id.md -->

---

## 阶段一：问题定位

1. 根据 Bug 描述，搜索相关代码文件，阅读并理解涉及的逻辑
2. 查阅 `docs/02_design/` 对应子目录下的设计文档，确认**预期正确行为**
3. 明确根因：
   - 是代码逻辑错误、边界未处理、还是设计文档遗漏？
   - 影响范围：哪些模块/接口/数据受影响？
4. 若 Bug 描述不足以定位，根据描述做最合理推断，在报告中说明

## 阶段二：回归测试（红灯）

1. 编写一个**能精确复现该 Bug 的测试用例**，写到项目既有的测试布局里（定位规则见下）：

<!-- @include templates/prompts/test-location.md -->

2. 测试命名格式：`应该_当<触发条件>时_<预期行为>`
3. 运行该测试，**确认测试失败（红灯）**，记录失败输出
4. 若已有相关测试但未覆盖该场景，在原测试文件中追加用例

## 阶段三：代码修复（绿灯）

1. 用**最小改动**修复 Bug，不改动与 Bug 无关的代码
2. 运行步骤二编写的回归测试，**确认通过（绿灯）**
3. 若修复过程中发现设计文档有遗漏或错误，同步更新对应设计文档

## 阶段四：全量测试验证

1. 运行该服务/应用的**完整测试套件**，确认没有引入新的失败
2. 若有 E2E 测试，运行相关 E2E 用例验证端到端行为正常
3. 如有测试因本次修复而需要更新（如快照测试、预期值变更），同步更新

## 阶段五：文档更新与最终报告

> ⚠️ **必须创建文件，不可仅在对话中输出。** 以下每份文档都必须作为实际文件写入磁盘。

1. 更新对应服务的 `CHANGELOG.md`，在 `[未发布]` 下新增 fix 条目：
   - 格式：`- 修复 <简要描述>（<触发条件>）`
2. 若涉及设计文档变更，同步更新 `docs/02_design/` 下对应文档
3. **【必须创建文件】** 在 `docs/04_testing/defects/` 下创建缺陷记录：`<缺陷ID>-<功能名>-defect.md`
   - **文档顶部必须包含 PDLC 追溯头**（格式见下方片段）：

<!-- @include templates/prompts/pdlc-trace.md -->

   - 记录：根因分析、影响范围、修复方案、回归测试覆盖情况
   - **创建后验证**：确认文件已存在于 `docs/04_testing/defects/` 目录
4. 输出最终报告（同时在对话中显示，**但报告内容必须已落盘到上述文件中**）：

```
## Bug 修复报告：<简要描述>（<缺陷ID>）

### 根因分析
<一段话描述根本原因>

### 影响范围
- 涉及文件：
- 涉及接口/功能：

### 修复方案
<描述做了什么改动，为什么这样改>

### 测试结果
- 回归测试：通过
- 全量测试：X 个通过 / 0 个失败

### 文档变更
- CHANGELOG.md：已更新
- 设计文档：已更新 / 无需更新

### 假设与说明
（记录执行过程中自行做出的关键假设）

### 上线前待办
（如有需要人工处理的事项，如数据修复脚本、缓存清理等）
```

---

## 产出物清单（每项必须作为文件创建）

| 产出物 | 路径 | 必须 |
|--------|------|------|
| 缺陷记录 | `docs/04_testing/defects/<缺陷ID>-<功能名>-defect.md` | ✅ 必须 |
| 回归测试 | 对应服务测试目录 | ✅ 必须 |
| CHANGELOG | 对应服务 `CHANGELOG.md` | ✅ 必须 |
| 设计文档更新 | `docs/02_design/` 下对应文档 | 按需 |

> **文件落盘规则**：所有带编号（缺陷ID）的文档必须作为实际文件写入，不可仅在对话中显示。最终报告完成前，必须确认上述文件均已创建。

## 要求

<!-- @include templates/prompts/output-language.md -->
- 只修复 Bug，不做额外优化或重构
- 回归测试用例必须保留在代码库中，不得删除
- 日期使用执行当天实际日期，格式 YYYYMMDD

Bug 描述: $ARGUMENTS

<!-- @include templates/prompts/state-update.md -->
<!-- @include templates/prompts/handoff.md -->