| 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. 找到根因
回答：
- 哪个输入或状态最先偏离预期；
- 哪个转换、默认值、生命周期、边界或并发假设被破坏；
- 报错点是根因还是最后暴露症状的位置；
- 现有接口、校验或测试为什么没有阻止它。
优先通过公开接口验证行为；若必须穿透巨大内部结构才能复现，先检查模块形状，而不是堆临时 mock（模拟）。
4. 做最小根因修复
- 只修改让根因消失所必需的代码；
- 保持无关行为和公开契约不变；
- 不提前加入未来能力，不顺手格式化或重构相邻模块；
- 不通过静默失败、放宽校验或修改错误断言掩盖问题；
- 测试中的 partial（局部对象）或故意错类型写法不得进入生产代码。
5. 验证与收口
- 重跑原反馈环，确认问题因预期修复而通过；
- 运行最相关测试，再按项目分层扩大到必要的集成、端到端、类型或构建检查；
- 检查差异、临时文件与调试日志；
- 用户可感知行为或发布语义变化时，同步项目要求的变更记录；
- 报告根因、修改、验证命令、结果和未覆盖边界。
完成后可用 507-review 做独立交付审查；用户明确要求提交时再用 507-commit。
合并冲突
- 列出全部冲突文件；
- 逐个理解当前版本和传入版本的意图；
- 采用最小解决方案，保留双方合理改动；
- 业务逻辑存在真实分歧时暂停并请求决策；
- 解决后运行相关构建和测试。
临时插桩
临时日志必须使用唯一、可搜索标记。修复完成前确认标记、临时脚本和一次性输出全部清理，不把调试产物或敏感数据带入交付。
完成与接力
- 完成信号：故障可复现，根因有证据，最小修复已通过相关回归与项目要求的测试层级，临时插桩已清理。
- 产物：修复代码、反馈环/回归证据、验证结果和剩余风险说明。
- 候选出口：测试资产本身需要处理时进入
507-test；职责或地图变化时进入 507-map；交付完成后进入 507-review；用户明确要求提交时再进入 507-commit。
- 回退条件：证据显示不是生产 bug、而是规格变化或环境问题时，停止修生产代码并路由到
507-grill、PRD 或测试环境处理。
