507-fix

name	507-fix
description	根因修复：已明确存在 bug、报错、崩溃、异常、回归或合并冲突时，先建立可重复反馈环，再以最小改动修复根因并验证。Use when user says fix, 修一下, 修 bug, 报错了, 崩了, 跑挂了, 有 bug, 修复报错, 合并冲突, 修复冲突, 修不通, debugging, error, crash, regression.

根因修复（fix）

从可复现信号出发定位根因，做最小修复，并用证据确认问题消失且没有引入回归。

职责边界

负责真实生产 bug、报错、崩溃、行为回归和合并冲突。测试本身是主任务时转 507-test；用户明确要求 test-first（测试先行）时转 507-tdd；不借修复之名做无关重构。

工作流程

1. 读错并界定问题

• 完整读取错误、stack trace（堆栈跟踪）和相关日志，不只看最后一行；
• 确认受影响行为、输入、环境、预期结果和最小范围；
• 区分生产 bug、规格变化、过时测试与测试环境问题；
• 读取报错点上下文，并沿调用和数据流向上游追踪。

2. 先建立反馈环

修改生产代码前，将最小复现固化为明确的 pass/fail（通过/失败）信号，例如：

• 失败测试；
• HTTP 请求或 CLI（命令行）重放；
• 无头交互；
• 最小脚本或 fixture（测试样本）。

没有确定信号时继续缩小范围或补充观测，不凭猜测修改代码。

3. 找到根因

回答：

1. 哪个输入或状态最先偏离预期；
2. 哪个转换、默认值、生命周期、边界或并发假设被破坏；
3. 报错点是根因还是最后暴露症状的位置；
4. 现有接口、校验或测试为什么没有阻止它。

优先通过公开接口验证行为；若必须穿透巨大内部结构才能复现，先检查模块形状，而不是堆临时 mock（模拟）。

4. 做最小根因修复

• 只修改让根因消失所必需的代码；
• 保持无关行为和公开契约不变；
• 不提前加入未来能力，不顺手格式化或重构相邻模块；
• 不通过静默失败、放宽校验或修改错误断言掩盖问题；
• 测试中的 partial（局部对象）或故意错类型写法不得进入生产代码。

5. 验证与收口

1. 重跑原反馈环，确认问题因预期修复而通过；
2. 运行最相关测试，再按项目分层扩大到必要的集成、端到端、类型或构建检查；
3. 检查差异、临时文件与调试日志；
4. 用户可感知行为或发布语义变化时，同步项目要求的变更记录；
5. 报告根因、修改、验证命令、结果和未覆盖边界。

完成后可用 507-review 做独立交付审查；用户明确要求提交时再用 507-commit。

合并冲突

1. 列出全部冲突文件；
2. 逐个理解当前版本和传入版本的意图；
3. 采用最小解决方案，保留双方合理改动；
4. 业务逻辑存在真实分歧时暂停并请求决策；
5. 解决后运行相关构建和测试。

临时插桩

临时日志必须使用唯一、可搜索标记。修复完成前确认标记、临时脚本和一次性输出全部清理，不把调试产物或敏感数据带入交付。

完成与接力

• 完成信号：故障可复现，根因有证据，最小修复已通过相关回归与项目要求的测试层级，临时插桩已清理。
• 产物：修复代码、反馈环/回归证据、验证结果和剩余风险说明。
• 候选出口：测试资产本身需要处理时进入 507-test；职责或地图变化时进入 507-map；交付完成后进入 507-review；用户明确要求提交时再进入 507-commit。
• 回退条件：证据显示不是生产 bug、而是规格变化或环境问题时，停止修生产代码并路由到 507-grill、PRD 或测试环境处理。