agentleFS
Sirius-JiSirius-Ji/dsh-disciplinary-skills-for-greenhands/recurring-root-cause-atlas/SKILL.md

recurring-root-cause-atlas

Skill1 starsChanged 10 days agoMITView on GitHub

Use when a bug feels familiar or keeps reappearing in new shapes — build a root-cause genealogy and match nine recurring archetypes (escaped newlines, implicit defaults, data never stored, encoding round-trip, delimiter collision, new predicate short-circuiting an old one, probe before commit, fixing only one of several identical call sites, configuring the wrong copy where the tracked file is not the executed one). 同一病根、反复出现、谱系、预防、配置不生效、改了没反应、钩子没运行.

The file

Files
SKILL.md

SKILL:同一病根反复出现

⚠️ 使用前提:如实报告失败(见 `你项目的状态文档 项目规范 §诚实报告失误)。

适用症状

  • "这个问题好像见过"
  • 某个 bug 修完,过一阵在别处又冒出来(症状不同、改法不同、但"手感"一样)
  • 同类事故第 N 次发生("上个月不是刚修过吗")
  • 修完之后心里知道它还会再来(但说不出"下次会以什么形态来")

不适用

  • 首次遇到的全新问题(先按 when-measurement-lies 走)
  • 事故已经造成损失(先按 source-code-recovery-from-pyc / windows-path-damage-diagnosis 恢复,再来归档)

快速判断(30 秒)

1. 这次的现象,能不能归到已有"病根"里?
       → 能 ⇒ 这是第 N 次:重点从"修"转向"改机制"
       → 不能 ⇒ 修完**必须**给这个新病根建一条谱系记录
2. 上一次是怎么修的?
       → 修在"症状层"(把这次的字符补回来)⇒ 一定还会再来
       → 修在"机制层"(让这一类不可能发生)⇒ 才算真修
3. 我能不能说出"下次它会以什么形态出现"?
       → 说不出 ⇒ 谱系还没建完

判据一句话:见过就先归族;问清这是第几次;然后改机制,而不是再打一个补丁。

⚠️ 更新(2026-10-06):新增病根 ⑤(字段分隔符与字段内容冲突) —— 写 skill 第一版时还没有这个实例(它是当天清理缓存时才踩到的), 所以"四类"变成五类。这本身就是本 skill 的用法:新病根要能挂进谱系,而不是当新故事讲。


做法:先建"病根谱系",再问"这是第几次"

谱系记录的最小字段(缺一不可):

字段为什么必须
病根(一句话)下次靠它认族;写"现象"是认不出的
各次形态同一病根在不同地方的表现不同,要能对上号
次数决定"打补丁"还是"改机制"
每次的 commit / 文件让后来者能查到现场(只用 commit hash 与内容描述,不用口头编号)
通用识别法下次怎么在 30 秒内认出它
预防(机制层)否则第 N+1 次必然发生

本项目九类病根谱系

病根 ①:\n / 反斜杠被"吃掉"

病根:文本经过了一层"不认识反斜杠"的转换(JSON 转义、正则字符类、shell 参数、字符串拼接), 反斜杠被当作转义符消耗掉,且不报错。

次形态commit / 位置
1JSON 转义吃掉 LaTeX 反斜杠:模型返回的 JSON 里 \neq 变成 neqbc4be29(某次改动:修复 JSON 转义吃掉 LaTeX 反斜杠 + 分段/回退加日志)
2正则字符类误删:\[3pt] 这类"行间间距"被 re.sub(r"\\[()\[\]]", "", …) 删成残留 3pt]cc2ae2d(改动 I-B1:修 \[<维度>] 被误删成 "3pt]" 的残留)
3shell 参数吃掉:-c "…\neq…" 到 Python 手里变成 …neq…bbc6388(把这条写进 source-code-recovery-from-pyc 反模式,+33 行)
4cmd /c 的 ^ 吃掉下一个字符:abc^:src/x.py → abc:src/x.py ⇒ git show 取到别的提交,"改动 0 行、全绿"其实是自己比自己2026-10-21 修 src/main.py 时踩到(详见 agent-execution-hygiene 规则 8)
5@"…"@(双引号 here-string)吃掉 Python 引号:"5.1" in A → 5.1 in A ⇒ 语法仍成立、语义静默改变(只在 TypeError 或得到错误结论时暴露)2026-10-21 第三次踩(前两次是 SyntaxError,这次是静默改语义);安全写法:代码写进 .py 文件,或内联用 @'…'@

通用识别法:只要"文本经手了一层"(JSON / 正则 / shell / 参数解析 / 模板),就比对字节级(repr() / ast.literal_eval), 不要看打印结果——打印在两个方向上都可能骗人(见 when-measurement-lies ① 工具层)。 (参数解析层与 3 号实例同族:^、引号、反斜杠都可能在进到程序之前就被改写,且都不报错。)

预防(机制层):文本传递一律"写进文件 + 用文件入口传"(如 git commit -F <文件>); 正则里出现反斜杠时,先写一条最小复现确认它匹配的是什么。


病根 ②:隐式默认值 / 顺序依赖

病根:某处行为取决于我没有显式设置的东西(库的默认值、父类的默认、上一次调用的残留), 或者取决于"谁后写"——后写的一方把先写的覆盖掉。

次形态commit / 位置
1度量与渲染用了不同的盒:量的是 \hbox(禁折行),渲染的是 $…$(会折行)⇒ 尺寸与实际不符cde6422(改动 A:公式度量与渲染口径统一,不再折行裁切)
2布局容器的默认内边距:SimpleDocTemplate 走 PageTemplate,其 frame 默认 leftPadding = rightPadding = 6 ⇒ 内容可用宽比"页面可用宽"少 12pt;按 493.23 钳制后仍越界 6.00pt081ab05(改动 M:图宽 521.85 > 可用宽 481.23)
3顺序依赖:folder_picker.refresh() 先 select(current, "") 把单元清空,末尾又调 _on_module_changed() 把刚选好的单元再清一次 ⇒ 单元选择被重置460320e(改动 J:修归档窗口"单元"选择被重置 + 落盘不同源)

通用识别法:

  • 症状是"我明明设了"⇒ 查默认值(谁在我之后写?库默认是多少?)
  • 症状是"有时对有时不对"⇒ 查调用顺序(把每次状态变化打出来,看谁覆盖了谁)

病根 ③:该存的没存

病根:某个数据只在"产生它的那一刻"可得,之后无法重建;但当时没有落库/落盘 ⇒ 永久丢失。 典型是"源码"与"原始输入"(渲染产物可以重做,源码不能反推)。

次形态commit / 位置
1笔记的 LaTeX 源码没落库 ⇒ 想重做 PDF 时没有依据(只能从渲染产物反推,不可靠)145e390(某次改动:录入时把 tex 写进 note_meta)
2归档草稿的原始 LaTeX 版没落库(question_tex / solution_tex)⇒ 某个资料库模块重做没有依据7805b78(改动 E:归档时把草稿的原始 LaTeX 版一起落库)

通用识别法:新增任何"有来源、且来源不可逆"的数据时,问一句:

这条数据的"源"在库里有吗?下次要重做它,靠什么?

预防(机制层):把"源"与"产物"同时落库(本项目:note_meta.tex 与 PDF 并存、 question_tex/solution_tex 与答案文本并存)。 注意:不要在写入前做任何"清洗"(如 clean_for_storage)——那正好把源打平,等于没存。


病根 ④:GBK / 编码往返

病根:中文 Windows 上,shell / 控制台 / 子进程的默认编码是 GBK, 而项目源码是 UTF-8 无 BOM ⇒ 读写经手一层就会静默损坏(拆字、少行、吃字符),不报错。

次形态commit / 位置
1Set-Content 往返把源码里的中文写坏(注释变 □,多字节字符被拆)事故报告 docs/recovery/事故及修复报告.md;恢复 SKILL 6ad54fa
2Get-Content 读行数少算:744 行读成 632(source-code-recovery-from-pyc 自身实测:195 vs 264)反模式节(bbc6388 的同族记录)
3-c / -Command 传参吃反斜杠:含 \neq 的字符串传给 Python 后被消耗bbc6388(反模式新增"+33 行")

通用识别法:中文 Windows + 经 shell 处理文本 = 可疑。 一律:读用 [System.IO.File]::ReadAllText($f, [Text.Encoding]::UTF8)(或 read 工具)、 数行用 ReadAllLines(显式 UTF-8)、传文本用文件不用参数。

预防(机制层):项目规范里已有四条 shell 禁令(见 source-code-recovery-from-pyc 反模式节, 以及 你项目的**状态文档** 项目规范"路径与编码"); **工具层**:能用 read/edit/write` 就不要经 shell。


病根 ⑤:字段分隔符与字段内容冲突(序列化往返)

病根:把结构化数据(记录 = 多个字段)写成按行 / 按分隔符的文本时, 字段内容里出现了分隔符本身(换行、\t、,、|…)⇒ 一条记录被拆成多条, 读回来条数变多、边界错位。

次形态commit / 位置
1公式含真实换行:写"将删清单"(TSV,一行一条)时未转义 ⇒ 读回来 2495 条(实际 2005)2026-10-06 清理公式缓存;状态文档 已知遗留"缓存键含派生参数"条目附记

这个病根的特征是"两边都不报错": 写的时候 write_text 正常、读的时候 splitlines() 正常 —— 只是条数悄悄变多。 唯一能抓住它的是"读回来先断言条数/结构"(本次靠 assert len(items) == 2005 拦下, 删除中止在执行之前、缓存完好)。

通用识别法:

  • 只要"结构化数据 → 文本文件 → 再解析",就问一句:字段内容里会不会出现分隔符? (本项目的高危字段:LaTeX 公式 —— 它天然含换行 \\、\n、&、|)
  • 读回来不要按行号定位记录边界,要按字段格式识别 (本次:首字段是 32 位 hex 的 stem ⇒ 才是新记录,否则是上一条的续行)

预防(机制层):

  1. 落盘前转义:s.replace("\n", "\\n")(本次修法就是把公式里的真实换行转成字面量 \n);
  2. 优先用 JSON / JSONL(json.dumps 天然转义字段内换行),而不是自制 TSV; 若必须用 TSV,写的时候逐字段检查/替换 \t 与 \n;
  3. 读回来先断言:条数、每条的字段数、关键字段的格式(如 hex 长度)—— 断言必须在"用它做事"之前。

病根 ⑥:新增判据时,先问"旧判据的触发条件在新逻辑里还可达吗?"

病根:把"新判据 + 旧判据"的或关系,写成短路 ⇒ 旧判据变成不可达分支(死代码), 而它承载的历史数据兼容 / 边缘场景全部失效。

本项目实例(FLAKE-4,2026-10-12): is_intentional() 的契约是"类名 或 stderr 白名单"。 新实现写成"按类名 ⇒ 若字段为空才读 stderr" ⇒ 类名对不上时不给 stderr 走白名单 ⇒ 白名单成死代码 ⇒ FLAKE-3 之前的历史归档(exception_type=RuntimeError) 被误判成"真异常档"。

检查动作(改任何"判据函数"时):

  1. 列出旧判据的全部触发条件;
  2. 逐条问:"在新逻辑下,这条还能成立吗?"
  3. 若不能 ⇒ 两个合法选择:
    • 明确删掉它(并在 commit 消息里说明为什么不再需要);
    • 把新判据写成"或"(不是"if 新: … else: 旧"的短路形式)。
  4. 加一条回归断言:喂一个"只命中旧判据"的输入 ⇒ 断言它仍走旧路径。 (FLAKE-4 的修法就是这条:回归测试已进自检 ⑪)

同族:SKILL-改动的验证要有证据 §断言要有灵敏度自证 —— 那条管"断言是否敏感", 这条管"旧分支是否还活着";两者都属"验证基础设施自身可能失效"。


病根 ⑦:临时探针之前必须先提交(或备份)

病根:工作树里同时有"未提交的修复"与"临时探针" ⇒ git checkout -- 想撤探针, 会把修复一起回退。

本项目实例(已第 2 次):

  • AK-2(2026-10-11):git checkout -- src/main.py 清掉尚未提交的修复;
  • 回归-4(2026-10-12):同上(老教训重演)。

检查动作:

  1. 加临时探针前 ⇒ 先提交修复(或 git stash / 备份到 data/tmp/);
  2. 撤探针时 ⇒ 只撤探针那部分(逐 hunk 或临时文件)。

病根 ⑧:同一根因的多个落点,只修了一处

病根:一个根因往往对应多个调用点 / 多个字段 / 多条路径。修好你手上那一处之后, 其余落点会以"换了个症状"的方式再犯一次。

  • 典型形态:同一个"查表的键"在 A 函数里查会失效,你把 A 修好了; B 函数用同一个键查另一个字段,仍然失效,但症状不同(A 是正文空白,B 是说明空白)。
  • 识别句:"这个修复,我在别的地方是不是也用过同样的写法?"
  • 动作:修完一处后全仓搜同款调用(同一个 API 名、同一段 SQL、同一个取数函数), 把"同源落点"一次清完;清不完就记在案卷里(哪个落点已知未修)。
  • 反模式:把第二次复发当成"新 bug"重新侦察——会白跑一遍,且再次只修一处。

病根 ⑨:配置了,但不是生效的那份

识别句:"我改的这个文件,真的是程序执行时读的那一份吗?"

这是假绿最隐蔽的一种形态 —— 改动本身没错,错在改错了对象。三种常见形态:

你以为在改实际生效的
仓库里的 .hooks/pre-commit$GIT_DIR/hooks/pre-commit
本地 .git/config 里的某项全局 ~/.gitconfig 或工作区级配置
多副本派生里的某一端程序真正读取的那一端

判据(30 秒自查)

  1. git config --show-origin --get <key> —— 看来源文件,不是看值;
  2. git rev-parse --absolute-git-dir —— 和 <repo>/.git 是不是同一个地方;
  3. .git 是目录还是文件?是文件(gitdir: …)就说明这是指针,真实仓库在别处;
  4. 改完立刻做一次可观测的最小动作(提交一次 / 跑一次脚本),看它是否打印你新增的那行。

机制层对策

  • 让被跟踪的文件成为唯一权威:git config core.hooksPath .hooks, 并把 $GIT_DIR/hooks/* 降级成转发器 exec "$ROOT/.hooks/pre-commit";
  • 凡是"配置 + 执行"分离的系统(钩子、CI、别名、profile 覆盖), 都必须能回答一句:"哪个文件是权威?" 答不上来就是定时炸弹;
  • 改动后用运行时证据(它打印了什么)而不是文件证据(文件里写了什么)自证。

反模式

  • ❌ 改完看到文件内容变了,就认为行为会变;
  • ❌ 假设 core.hooksPath 为空时走的是仓库内那份;
  • ❌ 靠"记得改两份"来维持两份配置一致。

预防清单("改机制"而不是"打补丁")

病根机制层对策
① 反斜杠被吃文本走文件入口;比对走字节级;正则先写最小复现
② 隐式默认值关键参数显式;对"后面会被改"的状态末尾重设或加顺序断言
③ 该存的没存新增数据时问"源在库里吗";源与产物同时落库;写入前不清洗源
④ GBK / 编码读写显式 UTF-8;计数走 [System.IO.File];传参走文件;能用文档工具就不用 shell
⑤ 分隔符冲突落盘前转义字段内分隔符;优先 JSON/JSONL;读回来先断言条数与字段格式
⑥ 判据被短路改判据函数时逐条问"旧触发条件还可达吗";要么明确删掉、要么写成"或";加一条只命中旧判据的回归断言
⑦ 探针回退修复加临时探针前先提交(或 stash / 备份);撤探针时只撤探针那部分
⑧ 多落点只修一处修完一处全仓搜同款;清不完就记入案卷(哪个落点已知未修)
⑨ 配置了没生效先问"权威副本是哪一份";--show-origin 查来源;改完用运行时证据自证

反模式

❌ 第 N 次当第一次修

每次都从头侦察、从头设计改法 ⇒ 效率低、且必然漏掉前面踩过的坑。 先翻谱系(本节 + `你项目的状态文档 已知遗留),再动手。

❌ 归档了病根,却不改机制

谱系只用来"知道",不用来"预防" ⇒ 第 N+1 次必然发生。 谱系的产出必须包含一条机制层对策。

❌ 只记现象、不记病根

"又出现 3pt] 了"——这是现象。病根是"正则字符类把反斜杠序列吃掉了"。 只记现象的人认不出换了个症状的同一个病根。

❌ 修在症状层

例:把这次被吃的 \n 手工补回来。补丁会随下一次经手再次消失。 要么改传递方式(文件入口),要么在选择层面避开(如不改判据而改 prompt)。

❌ 用口头编号当索引入口


边界

能归类

  • 有代码痕迹的(commit / 注释 / 测试)
  • 有文档痕迹的(设计稿 / 状态文档 / 事故报告)

不能归类

  • 只在对话里出现过的 ⇒ 必须落文档,否则无法归族(本项目:docs/design/ 与 状态文档 "已知遗留" 就是为此存在)
  • 不同病根但症状相似的情形 ⇒ 需要看"改法的方向",不能只看现象

需要人工裁决

  • "这两次算不算同一病根"(有时是边界判断)
  • 机制层对策的成本收益(如"全部改走文件入口"在一次性脚本里可能不值)

一句话

见过就先归族:把病根写成谱系,问清这是第几次,然后改机制而不是再打一个补丁。


谱系是靠"承认这是同一个病根"建起来的——把复发当成"新问题",谱系就永远建不起来。

实战案例与复盘

以下为该项目当时的一手记录,保留原始术语(项目名 / 模块名 / 改动编号),仅作方法论的实证注解。

  • ⚠️ 更新(2026-10-12):新增病根 ⑥(新增判据把旧判据短路 ⇒ 旧分支成死代码) ——
  • 实例来自卡片 FLAKE-4:验收当场抓到 is_intentional() 的白名单 fallback 成了不可达分支,
  • FLAKE-3 之前的历史归档被误判 ⇒ "五类"变成六类。
  • 同日再补病根 ⑦(临时探针之前必须先提交) —— 实例来自 AK-2 与回归-4(同一个病根第 2 次)
  • ⇒ "六类"变成七类。
  • 2026-11-05 补录 ⑧、⑨:⑧=同一根因多落点只修一处;⑨=配置了但未生效(钩子副本漂移,见实战复盘) ⇒ "七类"变成九类。
  • 预防(机制层):① 关键参数显式写死(不依赖库默认);
  • ② 对"会被别人改回去"的状态,在最末尾再设一次(卡片 J 的修法)或加顺序断言。
  • 对话里临时起的编号("方案 A-1""卡片 ③")在 git 里查不到。
  • 谱系条目只写 commit hash + 内容描述 + 文件路径。
  • | 1 | JSON 转义吃掉 LaTeX 反斜杠:模型返回的 JSON 里 \neq 变成 neq | bc4be29(卡片 37:修复 JSON 转义吃掉 LaTeX 反斜杠 + 分段/回退加日志) |
  • | 2 | 正则字符类误删:\[3pt] 这类"行间间距"被 re.sub(r"\\[()\[\]]", "", …) 删成残留 3pt] | cc2ae2d(卡片 I-B1:修 \[<维度>] 被误删成 "3pt]" 的残留) |
  • | 1 | 度量与渲染用了不同的盒:量的是 \hbox(禁折行),渲染的是 $…$(会折行)⇒ 尺寸与实际不符 | cde6422(卡片 A:公式度量与渲染口径统一,不再折行裁切) |
  • | 2 | 布局容器的默认内边距:SimpleDocTemplate 走 PageTemplate,其 frame 默认 leftPadding = rightPadding = 6 ⇒ 内容可用宽比"页面可用宽"少 12pt;按 493.23 钳制后仍越界 6.00pt | 081ab05(卡片 M:图宽 521.85 > 可用宽 481.23) |
  • | 3 | 顺序依赖:folder_picker.refresh() 先 select(current, "") 把单元清空,末尾又调 _on_module_changed() 把刚选好的单元再清一次 ⇒ 单元选择被重置 | 460320e(卡片 J:修归档窗口"单元"选择被重置 + 落盘不同源) |
  • | 1 | 笔记的 LaTeX 源码没落库 ⇒ 想重做 PDF 时没有依据(只能从渲染产物反推,不可靠) | 145e390(卡片 40:录入时把 tex 写进 note_meta) |
  • | 2 | 归档草稿的原始 LaTeX 版没落库(question_tex / solution_tex)⇒ 集题本重做没有依据 | 7805b78(卡片 E:归档时把草稿的原始 LaTeX 版一起落库) |
  • 病根 ⑧ 的实证(同一根因,两次犯):持久化记录里的 note_hash 是"生成当时产物的摘要", 产物被重新生成后磁盘摘要就与库里不一致 ⇒ 按摘要查库必然查空。 第 1 次:修了 tex(正文)—— 按笔记名兜底;第 2 次:note(说明)走的是同一段查库逻辑, 我漏了 ⇒ 打开"修改"弹窗正文有了、说明仍空。第 2 次补上后两条才都正常。
  • 同源的第二个信号:这条链上还有第三个落点(归档入口按摘要取附件),当时同样未修;已记入案卷待处理。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.