/pdlc-fix

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-review
terminal_state: fix_done

全自动 Bug 修复

<!-- @include templates/prompts/iron-law.md（已内联于下方，无需另读） --> ⛔ **IRON LAW · 不可违反的硬门禁**

以下规则为**不可协商**的执行约束：

1. **文件必须落盘**：所有带编号（功能ID / 缺陷ID）的文档，必须作为实际文件写入磁盘，不可仅在对话中输出。 2. **阶段必须落章**：每个阶段完成后必须在状态机 `docs/.pdlc-state/<feature-id>.json` 追加 history，不可跳过。 3. **测试必须存在**：进入 `/pdlc-implement` 前，对应测试必须存在且处于红灯状态。违反则中止。 4. **自检必须执行**：段二自检为强制步骤，不得以"已经很好了"为由跳过。 5. **防循环**：段三修复为单次，不递归。无法自动修复的问题记录到报告，继续往下走。 6. **状态必推进**：成功执行某 phase 后 `current_stage` 必须变更。收尾时若发现 `current_stage` 未推进，视为失败并报错，**不得静默返回**（防止外层循环拿滞后的状态空转烧额度）。唯一例外：命中人工点主动 block 时，`current_stage` 保持不变但必须写 `last_phase_result.ok=false` + `blocked_reason`。

**违反任一条 = 立即中止当前命令，输出违规详情，等待人工介入。** <!-- @include-end templates/prompts/iron-law.md -->

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

执行规则

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

---

<!-- @include templates/prompts/defect-id.md（已内联于下方，无需另读） -->

缺陷ID分配（必须执行）

1. 获取当前日期与时分秒：`date +%Y%m%d`、`date +%H%M%S` 2. 生成缺陷ID：`B<YYYYMMDD>-<HHMMSS>`（示例形如 `B20260717-122801`；用执行时的真实日期与时分秒） 3. **本地防撞**：若该 ID 已被占用（`docs/` 或 `docs/.pdlc-state/` 下已有同名前缀），重新读取 `date +%H%M%S` 重取（生成本身有耗时、通常已跨秒；若仍同秒则 `sleep 1` 后再读一次，**不手算时分秒**，天然处理跨天边界） 4. 从 Bug 描述中提取功能名关键词（英文小写+连字符）

**为什么用时分秒而非序号**：多人 / 多 AI 并行时各自独立取「当日序号 max+1」会分到相同编号、合并冲突。改用创建时刻 `HHMMSS` 后各副本零协调也几乎不撞（仅同一秒才可能），文件名互异、git 自动合并。旧的 `B<日期>-<NN>` ID 仍有效、可解析。

**注意**：日期与时分秒使用执行时的实际值。 <!-- @include-end templates/prompts/defect-id.md -->

---

阶段一：问题定位

1. 根据 Bug 描述，搜索相关代码文件，阅读并理解涉及的逻辑 2. 查阅 `docs/02_design/` 对应子目录下的设计文档，确认**预期正确行为** 3. 明确根因：

• 是代码逻辑错误、边界未处理、还是设计文档遗漏？
• 影响范围：哪些模块/接口/数据受影响？

4. 若 Bug 描述不足以定位，根据描述做最合理推断，在报告中说明

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

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

<!-- @include templates/prompts/test-location.md（已内联于下方，无需另读） -->

测试代码在哪（布局无关的定位规则）

> ⚠️ **这条规则的要害**：红灯守卫必须区分「**项目没有测试**」和「**测试不在我预期的位置**」。 > 前者才该拦；后者拦了就是误伤——真实项目的测试布局千差万别（单体 `backend/tests/`、 > 根级 `tests/`、Go 同包 `*_test.go`、Node 与源码同目录的 `*.test.tsx`…）， > 按一份写死的路径清单去找、找不到就拦，会让 pdlc 在大量正常项目上直接卡死。

**核心原则：优先问 runner，其次翻文件。** 测试框架自己最清楚有哪些测试—— 让它报比我们去猜文件位置准得多，也和 pdlc「信退出码、不信目视检查」的哲学一致。 尤其**测试写在源文件里**的语言（见下），翻文件根本找不到。

按下列顺序定位，**命中即停**：

1. 项目自己的声明 + 向 runner 查询（最高优先级）

若存在 `docs/00_standards/test-commands.yml`，它的 `unit` / `e2e` 命令**就是权威**—— 项目已经明确告诉你测试怎么跑。**用它去问 runner**，而不是去翻目录：

| runner | 列出全部测试 | 只查某功能相关 | |---|---|---| | cargo (Rust) | `cargo test -- --list` | `cargo test <关键词> -- --list` | | pytest | `pytest --collect-only -q` | `pytest --collect-only -q -k <关键词>` | | go test | `go test -list '.*' ./...` | `go test -list '<关键词>' ./...` | | vitest / jest | `npx vitest list` / `--listTests` | `npx vitest list -t <关键词>` | | gradle / maven | `--tests '*'` 干跑 | `--tests '*<关键词>*'` |

**查询结果为空 = 该功能没有测试**（这是行为证据，比"我没找到文件"可靠得多）。

2. 测试写在源文件里的语言（**必须靠内容匹配，文件名扫描无效**）⭐

这类语言没有独立测试文件，只能按**代码内标记**搜：

| 语言 / 框架 | in-source 测试标记 | |---|---| | **Rust** | `#[cfg(test)]`、`#[test]`、`mod tests` | | **Vitest**（in-source testing） | `import.meta.vitest` | | **Python** doctest | docstring 里的 `>>> ` | | **Elixir** doctest | `@doc` 里的 `iex>` | | **Go**（同包但独立文件） | `*_test.go` + `func Test` |

> ⚠️ **Rust 尤其要注意**：单元测试几乎总在源文件的 `#[cfg(test)] mod tests` 里， > `tests/` 目录按 Cargo 约定只放**集成测试**。所以「`tests/` 目录不存在」在 Rust 项目里 > **完全不能推出「没有单元测试」**——照文件清单判红会稳定误伤所有 Rust 项目。

3. 常见布局约定（按项目实际技术栈挑，不要全试）

| 生态 | 常见测试位置 | |---|---| | Python | `tests/`、`backend/tests/`、`test/`、与源码同目录的 `test_*.py` | | Node / TS | `tests/`、`__tests__/`、`src/**/__tests__/`、与源码同目录的 `*.test.ts(x)` / `*.spec.ts(x)` | | Rust | 源文件内 `#[cfg(test)]`（单测）+ `tests/`（集成测试） | | Go | 与源码同包的 `*_test.go` | | JVM | `src/test/java/`、`src/test/kotlin/` | | Ruby | `spec/`、`test/` | | 微服务 / 单体仓 | 上述任一可能出现在 `backend/`、`backend/services/<名>/`、`frontend/<应用>/` 之下 |

4. 文件名兜底扫描

前三步都没命中时，按文件名模式全仓搜（`*test*` / `*spec*`，排除 `node_modules`、 `.venv`、`vendor`、`dist`、`build`、`target`、`.git`），再按功能关键词筛。

5. 判定

• **任一步找到相关测试** → 通过，进入下一步（`pdlc-implement` 还需确认红灯）
• **四步走完确实找不到任何测试** → 这才是真红灯，按各命令的守卫规则中止
• **找到测试但与本功能无关** → 按「本功能无测试」处理（同样是真红灯），但报告里要说明

「项目有测试，只是没覆盖本功能」，别让用户以为项目裸奔

• **无法判定**（如 runner 装不上、语言不认识）→ **不要默认放行，也不要假装找到了**：

如实报「无法确认本功能是否有测试」并交还人类。**「我判断不了」绝不等于「没问题」。**

> 写测试时（`pdlc-tdd`）同样按本规则决定**写到哪**：跟随项目既有布局与惯例—— > Rust 单测就写进源文件的 `#[cfg(test)] mod tests`，**不要**为了迎合某种预设结构 > 新造一套平行的测试目录。 <!-- @include-end templates/prompts/test-location.md -->

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

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

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

阶段四：全量测试验证

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

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

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

1. 更新对应服务的 `CHANGELOG.md`，在 `[未发布]` 下新增 fix 条目：

• 条目格式 `- <简要描述>（<功能ID 或缺陷ID>）`；`[未发布]` 里已有同一 ID 的条目就不再追加（`/pdlc-ship` 按 ID 去重）；描述以「修复」开头，触发条件写进描述里

2. 若涉及设计文档变更，同步更新 `docs/02_design/` 下对应文档 3. **【必须创建文件】** 在 `docs/04_testing/defects/` 下创建缺陷记录：`<缺陷ID>-<功能名>-defect.md`

• **文档顶部必须包含 PDLC 追溯头**（格式见下方片段）：

<!-- @include templates/prompts/pdlc-trace.md（已内联于下方，无需另读） -->

PDLC 追溯头（文档顶部必须包含）

每个带编号的文档必须以下列注释开头：

<!-- PDLC-TRACE -->
<!-- 功能ID: <F/B 开头的 ID> -->
<!-- 功能名称: <kebab-case 名> -->
<!-- 阶段: <requirements | design | tdd | impl | review | e2e | ship | deploy | retro> -->
<!-- 前置文档: <上一阶段文档路径 | 无> -->
<!-- 创建时间: <执行时的实际 ISO 8601 时间戳> -->
<!-- 关系: <type=id; ... | 整行省略> -->

**严禁**把占位符（`<...>`）或示例日期原样写入实际文档。必须用真实值替换。

**关系行（RFC#6，可选）**：表达 feature 间关系链。无关系时**整行省略**（保持旧文档有效）。语法 `type=id` 对，多 id 用 `,` 分隔、多对用 `; ` 分隔，例：`<!-- 关系: extends=F20260510-100000; depends_on=F20260501-090000 -->`。6 种类型：`extends` /