Ren fix

ren-fix

启动必读

先 Read .ren-flow/attention.md。

工作区模式（根 attention.md 标 mode: workspace）：制品按业务域分层 —— 本技能产物落到 .ren-flow/domains/{domain}/ 下而非 .ren-flow/。先确认本次业务域（域清单见根 attention），再 Read .ren-flow/domains/{domain}/attention.md 取该域约定。

这个技能干什么

修 bug 的直觉是「找到错的地方改了完事」,这个直觉反复制造麻烦:现象没留存、根因没碰只改了表面、范围扩散、没验收闭环。ren-fix 在「看到问题」和「改代码」之间塞缓冲:

记录现象 → 定位根因 → 定点修复 + 验证

铁律(来自系统化调试方法论):未完成 Phase 1 根因调查,不得提出修复;禁止猜修、禁止只打症状补丁。压力越大越要走流程——「就改一行就好」「赶紧上线」「之前试了几个修法都没用」这些场景最需要全程,不是跳过流程的理由。

产出一个修复目录 .ren-flow/fixes/{YYYY-MM-DD}-{slug}/,主文件 {slug}-fix.md;复现脚本、日志片段、前后对比等伴生文件一并放进这个目录。日期取发现问题当天,slug 一眼看出是什么问题(null-on-empty-list)。这份记录是回溯凭证 —— 没它下次同类问题只能从 git log 反推。

先判复杂度:快路还是全程

快路(三条同时满足):AI 读完代码对根因高度有把握(能指出 file:line + 原因)/ 修复改动很小(1-2 处)/ 无跨模块影响。 → 流程压缩:读代码 → 直接告知根因 + 修复方案 → 用户确认 → 修 → 验证 → 写 fix 记录。

全程(任一命中):根因有多个候选 / 修复涉及多模块 / 需先复现才能定位 / 用户要完整存档。 → 走下面三阶段。

三阶段

阶段 1:记录现象

先 Grep .ren-flow/fixes/ 用关键词(报错信息 / 模块名)扫一遍 —— 同类 bug 以前修过的话,历史记录的根因和解法能直接复用。

和用户对齐并写下:观察到的现象(报错信息 / 错误行为)、复现步骤、期望行为、影响范围。现象描述要具体到能复现 —— 模糊的「有时候不对」要追问到可复现。

阶段 2:定位根因

AI 读代码分析,用户确认。核心:沿调用链回溯到原始触发点,不在报错处治标。

回溯步骤:

1. 观察症状 —— 报错信息 / 错误现象,精确记下。
2. 找直接原因 —— 哪行代码直接产生了这个错误。
3. 逐层上溯 —— 问「是谁调用了它?传进来的值是什么?」一层层往上,直到找到那个值最初从哪来。
4. 定位原始触发点 —— 错误数据 / 错误状态最早是在哪产生的,那里才是根因。
5. 报错那一行往往只是症状 —— 在症状处打补丁,深层问题下次照爆。

追不动时加插桩:在出问题的操作之前打日志,带上下文(参数、调用栈 new Error().stack、相关环境变量),跑一遍抓输出再分析。

多组件场景的证据收集:涉及 CI→构建→签名 / API→Service→DB 这类链路时,每跨一层就收一份证据(日志 / 状态码 / 中间产物),不要靠"应该是上游的问题"猜测——错位的证据是定位错根因的头号原因。

纪律:

• 失败的尝试也记下来:试过哪些假设、为什么排除 —— 对后人是宝贵信息。
• 根因不唯一时,把候选都列出来,说明怎么进一步区分,不硬选一个。
• 给出 file:line 级的根因定位后,再谈修复方案。
• 多层防御:根因修在源头之外,可在沿途几层各加一道校验(如入口校验参数、关键操作前拒绝非法状态),让同类 bug 更难复发。

阶段 3:定点修复 + 验证

• 只改根因相关的地方:发现一个 bug 顺手改五处会引入新问题且无法追溯。其他问题记成新的 fix。
• 修完按复现步骤验证 bug 消失,并确认没碰坏邻近功能。
• 写修复记录 fixes/{YYYY-MM-DD}-{slug}/{slug}-fix.md —— 模板见 references/record-format.md(含 frontmatter 字段与现象 / 根因 / 修复 / 验证四节)。快路也要出,只是「现象 / 根因」可简短。

归档

修复稳定或确认非 bug 后归档 —— 路径与 frontmatter 改法同 references/record-format.md 的「归档」一节。

与 ren-spec 的边界

• fix:本来应该好的东西坏了 —— 已有代码的 bug / 异常 / 文档错误 / 性能问题
• spec:从来没有的东西要加进来 —— 新功能
• 灰色地带:修 bug 中发现需要新增能力才能根治 —— 先把 fix 的记录和分析做完,再视情况开 ren-spec,不在 fix 里偷偷做新功能。

退出条件

• 根因定位到 file:line,不是停在症状
• 修复范围只覆盖根因,顺带发现的其他问题已另记
• 按复现步骤验证 bug 消失,邻近功能没坏
• 修复记录落在 fixes/{YYYY-MM-DD}-{slug}/{slug}-fix.md,frontmatter 含 tags / summary
• 值得沉淀的坑已提示 ren-note

容易踩的坑

• 改了报错那一行就收工 —— 根因可能在上游
• 顺手修一堆别的 —— 范围扩散,出事追不回
• 现象记得模糊 —— 三个月后无法复现
• 根因有多个候选时硬选一个
• 修完不验证 / 只验 bug 本身不看邻近功能