---
name: fix-bugs
description: 修复现有软件的崩溃、错误结果、失败测试或性能回退；复现症状、定位根因并复测原场景。
---

# 修复缺陷

以用户症状为验收对象，按 S0–S7 的证据状态推进。已有可信观察可满足对应出口；用现有 issue、工作记录或上下文保留 `状态｜命令/操作｜观察｜下一实验`，回退时同步更新。只读原因分析止于 S0–S4，交付证据与未决项；获准修复才进入 S5。

## S0 界定故障

记录实际与期望行为、触发输入、版本/环境和影响范围。读取项目约束、相关实现、检查入口及已有上下文/ADR；关键事实先从仓库与输出补齐，仍缺失时索取最小信息。

出口 → S1：能用同一判据识别症状出现或消失。

## S1 建立红灯

运行用户复现或已有检查，记录可重跑的输入、步骤、预期和实际结果。**红灯**是实际运行过、经过故障路径且因同一症状失败的检查。固定时间、随机数、数据与配置；慢场景另建快循环，原场景留给 S6。

缺入口、人工操作、偶发采样或性能问题 → 读取[反馈循环](references/feedback-loops.md)对应分支；采集/回放数据 → 读取[采集与回放](references/feedback-loops.md#采集与回放)；未观察到症状 → 执行[无红灯分支](references/feedback-loops.md#未能建立红灯)。

出口 → S2：已观察到同一症状的红灯；独立不变量反例按无红灯分支转 S4。

## S2 缩小反例

保留原始场景，每次删减一个输入、步骤或依赖并重跑；红灯消失就恢复该项。偶发故障保存同条件的失败次数/总次数，修复后沿用采样条件比较。

出口 → S3：缩小后仍是同一症状，剩余因素已核对或列为未排除项。启动错误或另一症状 → S1。

## S3 写出可证伪假设

复杂故障列 3–5 个竞争原因，按证据和检验成本排序；每项写出成立时的预测及推翻条件。明显单点错误直接检验。

出口 → S4：至少一个实验能区分主要候选；预测说不清 → S2 补观察。

## S4 核实根因

每个探针检验一条预测、改变一个关键条件。优先断点或局部检查；临时日志放在分歧边界并加唯一前缀。比较正常与失败状态，找到首次偏离。

保留能随疑似条件开关而变化的红灯对照；无法开关时，用轨迹和不变量证明「触发 → 错误路径 → 症状/违反的不变量」，列出未排除解释。性能原因由反馈循环中的基线和 profiler/查询计划支持。

出口 → S5：证据支持根因，主要替代解释已排除；假设被推翻 → S3，信号失效 → S1。

## S5 固定并修复

在真实故障模式的测试接缝确认旧行为为红，再实施最小修复，使**同一检查**转绿。自动测试若仅复述内部实现，保留固定的人工/集成复现并标明自动化缺口。

公开 API 行为变化 → 用 `design-apis` 核对兼容影响。扩大访问、生产写入或高成本探针按相应授权执行。

出口 → S6：针对性检查或固定人工复现由红转绿；仍红按新证据回 S3/S4 或留在 S5。

## S6 原场景回归

依次复测原始未缩小场景、针对性检查及受影响的相邻正常行为，说明相邻检查的选择依据。按本次引入、旧失败、环境阻塞分类；修复本次新失败再验。必要的针对性或相邻检查受阻时留在 S6。

搜索并移除临时日志前缀，只清理本次创建且无需保留的探针/夹具。原场景缺输入或环境时记录阻断及替代场景的对应关系。

出口 → S7：针对性与受影响检查通过，原场景的结果或无法复测的原因明确；新失败 → S3/S5。

## S7 交付

| 结论 | 条件与用语 |
| --- | --- |
| 完整交付 | 原始场景已复测、原症状消失，受影响检查通过；可称「原问题已修复」。 |
| 有限交付 | 原始场景缺输入/环境，但替代复现或独立不变量检查由红转绿，受影响检查通过；只声明已修复的独立行为，原症状仍未知，列对应关系与缺口。 |
| 未完成 | 停在 S0–S6 或证据不满足以上条件；报告当前状态与缺失证据。 |

报告症状、根因证据、改动、实际命令/结果及未覆盖范围。秘密替换为 `<REDACTED>`；获准创建提交或 PR 时沿用根因与验证证据。