English version: SKILL-en.md

self-review —— 提交前的 git diff 自评审

一句话：commit 之前，把"我这次改了什么"当成别人的补丁读一遍——先读全量、再跑机械门、再按失败族逐条查，最后按三档给结论（已修 / 待定 / 不成立）。评审不是"再看一眼"，是按清单找具体的失败形态。

何时用

• commit 之前——尤其改了脚本、判据、文档口径、跨仓引用面（这几类错了都不报错，只静默失真）
• 用户说「git diff 自我评审」「提交前检查」「自查改动」

何时不用

• 归档物不评审：说了 archive / 冻结的东西按现状冻结——不要给它补一致性、不要跑它的自证套件、不要为它写记版。被发现真实分歧时一句话陈述事实即可，附不附方案由对方定。
• 别人写的代码要正式评审 → /open-code-review（OCR）。
• 纯 Markdown 文字 / 排版 → /doc-reviewer。
• 只管本次 diff：不顺手扩张到整个仓库、不重构未被改动的部分。

流程（六步）

1. 圈定面

git status --short          # 谁改了、谁暂存了——**别人暂存的不要动**
git diff --stat             # 规模
git diff --cached --stat    # 已暂存面

多来源改动（我 + 用户 / 多个会话）时，先把属于我的路径列出来，后面每步只对这一组负责；提交时用 git commit -- <paths> 路径限定，防止顺手吞掉别人的暂存。

⚠️ 先确认"改动在哪个仓/worktree"（2026-09-29 实证）：跨仓工作（主仓 + 若干 worktree）时，在 A 仓跑 git status 打"clean"、而改动全在 B worktree——这不是干净，是看错了地方。手法：

git -C <tree> status --short          # 每个候选树各跑一次；HEAD 也报一句
git worktree list                     # 同仓的其它 worktree 一并列

纪律：零改动 = 坐标问题，不是"没事"——停下来换树，别继续往下走（mech-gates.sh 现在对此 exit 2 并列出其它 dirty worktree，就是为了不让它读成绿）。

2. 读全量 diff（不许抽样）

git diff -U2 -- <paths> > /tmp/rev.txt && wc -l /tmp/rev.txt

大 diff 分片读（Read 带 offset/limit），逐簇读：脚本 / 判据 / 文档 / 数据。抽读 = 漏读——被漏掉的那一段恰恰是问题所在（实证：一条用法串漏参数、一处计数口径过时，都只在全量读时才露头）。

3. 机械门（机器能判的先让机器判）

脚本随本技能目录分发，<SKILL_DIR> 即本技能的安装目录：

bash <SKILL_DIR>/scripts/mech-gates.sh          # 取 git diff --name-only HEAD + 未跟踪
bash <SKILL_DIR>/scripts/mech-gates.sh <paths>  # 指定文件

它做：bash -n（shell 语法）、ast.parse（Python，不落 pyc）、冲突标记、尾空白。

再加上该改动面自带的门——前提是那个对象还在跑：项目自己的单测 / 自证套件 / 参数断言 / 配置解析。跑完把命令与结果写进结论（"bash -n ×5 过"这种一句话就够，别贴全文）。

记门跑在哪个码上：脚本会先打「受检仓 + HEAD」；远端门（ssh 跑容器/机台）再补一句树 / 镜像 / commit——只写"已跑"等于没写（下一次没人能判断那份证据是否覆盖这份 diff）。

评审者自己的取证命令也要过 C3：ssh … | tail、cmd | head 会把远端退出码换成管道的（tail 恒 0）⇒ 远端失败静默通过。用 set -o pipefail，或人工读关键串（本次实证：e2e 的 PASS 是我读出来的，不是退出码给的）。

4. 按失败族逐条查（这一步才是评审）

清单见 references/failure-classes.md——六族：判据 / 失败方向 / 静默失败 / 口径一致 / 跨仓跨机 / 提交面。

逐族问一遍：不要求每条都中，但不许跳过不看。规则按「族 + 序号」编号（A1…F6）：速查表给一句话，编号细则给完整查法与实例；结论里引用规则直接用编号（如「见 C3」）。

5. 怀疑即实测（纪律）

对任何"我怀疑这里有问题"的想法：要么当场用最小实验证伪/证实，要么标成「未验证」——不许凭臆想进结论让对方改不存在的问题。

• 反面教材：怀疑新增的 prune 在"本地清单为空"时会把整棵远端树判成残留、PRUNE_RM=1 删光。逐条实测（set -euo pipefail 下命令替换失败 ⇒ 中止；[ -f x ] && . x 属于 set -e 豁免形态）⇒ 不成立，如实写成"不成立"而不是"建议加守卫"。
• 实测要复刻同款壳：同一个 set 组合、同一种重定向/管道形态——壳不同，结论不算。

6. 证据与被审代码必须同一份

结论里引用的外部证据（真机轮 / 他人日志 / 容器全量）只对它当时那份码有效。自审过程中往往还会改文件（改注释、加强断言、补文档），改完有两种合规收尾：

1. 复跑该门（首选，尤其改了行为面）；或
2. 显式声明差异面并给佐证——"此后改动仅注释 / 测试 / 文档，行为面未变"，佐证如 git diff 落在哪些文件、grep -c <变异标记> 为 0（防变异测试忘了回滚）。

不许默不作声地把旧证据挂在新码上。（实证：一轮自审后改了 4 处文件，靠一句"此后改动仅注释/测试/文档"的声明 + grep -c MUTATION-CHECK 为 0，才说得清"e2e 未复跑但结论仍成立"。）

结论分三档（不写"建议关注"这种模糊话）

总长控制在能一眼扫完：一屏表格 + 每档几条。评审报告不是论文。

评审通过之后

提交前再跑一次机械门：自审本身会改文件（已修那几条），门要在最终那份码上过一遍。

提交面有三条硬坑（细节见 failure-classes §F）：路径限定只带指定路径、重命名要提两半、message 先落盘再提交（钩子中止后重试别重打——重打容易顺手写短，落库就成了短版）。提交动作本身要当场授权，一次授权不覆盖下一批。