agentleFS
Sirius-JiSirius-Ji/dsh-disciplinary-skills-for-greenhands/when-to-rollback-or-not-change/SKILL.md

when-to-rollback-or-not-change

Skill1 starsChanged 10 days agoMITView on GitHub

Use when a third patch on the same spot still fails, when measurements contradict the premise, when the user reports a regression you just introduced, or when deciding whether to revert — five criteria, layer-mismatch alarms, an idempotence self-check, an executable rollback checklist, and the anti-patterns around sunk cost and undocumented no-change decisions. 回滚、不改、沉没成本、半成品、逐字节复核.

The file

Files
SKILL.md

SKILL:何时该回滚 / 不改

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

适用症状

  • 改到一半发现不对,但不想认(沉没成本:"都改这么多了")
  • 调研完在"改 / 不改"之间摇摆(两种说法都像有道理)
  • 在同一个架构上补丁越打越多(第 3 个、第 4 个补丁开始互相打架)
  • 实测结果与预期相反(方案的前提被推翻)
  • 半成品已经动过用户的数据 / 文件,不知道该不该撤

不适用

  • 改动还没落地(只在脑内/草稿)⇒ 直接改方案即可,不存在"回滚"
  • 已经修复完成且验证通过 ⇒ 那是"正常收尾",不是回滚场景

快速判断(30 秒)

1. 门禁红了吗?
       ├─ 红了 ──▶ 这个半成品会让"已发布的效果"退化吗?
       │              ├─ 会 ──▶ 【回滚】
       │              └─ 不会 ─▶ 修到绿(但设一个次数上限)
       └─ 绿 ───▶ 2
2. 调研是否证明"不改更优"?
       ├─ 是 ──▶ 【不改】:留档理由 + 当时数字 + 触发条件
       └─ 否 ──▶ 3
3. 在**同一个架构**上,这是第几个补丁?
       ├─ ≥ 4 ──▶ 【停下】:回到架构层(重写 或 回滚)
       └─ ≤ 3 ──▶ 继续(但每次补丁后都要重跑门禁)
4. 实测结果与方案前提**相反**?
       └─ 是 ──▶ 【撤销】该改动,并把"反了的实测"写成结论

判据一句话:门禁红 + 会退步 ⇒ 回滚;调研证明不改更优 ⇒ 留档不改;同一架构补丁过三 ⇒ 停下。


五条判据(展开)

判据 1:门禁红 且 半成品会退化已发布效果 ⇒ 回滚

重点在**"已发布效果":仓库里已经能用、用户已经在依赖的行为。 半成品即使"新功能是对的",只要它让旧行为变差**,就不能留在树上。

判据 2:调研后"不改更优" ⇒ 记录理由,不改

"不改"是一个需要产出物的决定,不是"什么都不做"。必须留三样:

  1. 不改的理由(为什么改会更差)
  2. 当时的数字(将来有人再提,直接拿数字回复)
  3. 触发条件(什么情况下应该重新考虑)

判据 3:在错误架构上叠补丁 > 3 次 ⇒ 停下

补丁是局部修正;当第 4 个补丁要"绕过前 3 个补丁的产物"时,说明架构错了。 此时继续补的代价是超线性的(每个新补丁都要考虑前面所有补丁的相互作用)。

判据 4:实测与方案前提相反 ⇒ 撤销,并记录"反了的实测"

前提被推翻时,"修一修再用"通常是错的方向——因为方案的理由已经不存在了。

判据 5:动过用户数据 / 文件 ⇒ 先保全,再撤,撤完逐字节复核

撤文件不是"删掉新文件"那么简单:要放回备份并核对字节, 否则"看起来回来了"其实已经不一样了。

删除前的回滚能力(回收站)见 change-verification-with-evidence §删除也是一种改动 —— 撤销一个"删除"动作,前提是当初的删除本身可恢复:用户数据与未追踪产出必须走回收站, 否则回滚清单上根本没有可执行的步骤(git 救不回未追踪文件)。


本项目已执行的 5 次(完整清单)

#类型内容commit证据 / 复核方式
1回滚某个资料库模块切片器重写(run 扫描 + 事后回填)架构错误 ⇒ 回滚到某次改动,只留设计稿回滚点 23b6a5e("某次改动:剥无环境片段行首的 &");后来的重写实现是 9d8c85fdocs/design/某次改动-切片器tokenizer重写.md 首行原话:"DSH 上一次 46c 实现(run 扫描 + 事后回填)架构错误,已回滚(HEAD 回到 23b6a5e 某次改动)。本稿只做设计,不含实现。"
2回滚某个资料库模块"重做"尝试(现场试做后明显更差:矩阵散成行内小图、2 页)276baa7(截图:某个资料库模块重做尝试,方案不成立,已回滚)设计稿 §3.3.5:os.replace 放回备份 ⇒ 复核 1 页 / 13 图 / 229504 字节,与备份逐字节一致
3撤销行内公式图垂直对齐调研里的一个子方案(valign = -(depth_pt),去掉 border 项):实测反了调研留档 f7ac3f9;对照图 6e02c0d该子方案的实测结果与预期相反(改了反而更差)⇒ 当场撤销,不进入候选;最终结论见 状态文档"行内公式图垂直对齐调研(结论:不改)"
4不改行内公式图垂直对齐(整体不改):6 档对照后判定"改会造成更差的效果"f7ac3f9(状态文档 记"结论:不改")+ 6e02c0d(6 档对照截图)关键数字:顶对齐(valign = 字身上升 − 图高)能让 8 张图的"上缘−基线"全部等于 8.53,但 36.58pt 的 \sum 图下缘会垂到 −28.05;统一 display=False 会让图变矮(36.58 → 17.61)却把压行盒数从 1 变成 2
5不做\text 中性命令的语义区分(判据设计完成后决定不做)edc1908(设计稿 §3.3.3"决定不做")反例数据:把 \text 加进白名单会把纯中文小标题 \text{计算顺序与规则:} 判成公式 ⇒ 中文被渲染进图(全库对拍实测)

⚠️ 第 3 条(撤销 K③)缺数字留档:该子方案(valign = -(depth_pt))只存在于调研对话中,无独立 commit ⇒ 无数字留档。结论本身已撤销,不影响现状(当前 valign 仍是原方案)。 若将来补到当时的实测数字,应补进本行 —— 在此之前,本条只能作"发生过一次撤销"的记录,不能作数字依据。


回滚操作清单(可执行)

1. 【保全】把现场的损坏/半成品状态冻结一份(复制,不是移动)
2. 【备份】待撤的文件/数据 → 带日期的备份目录(copy)
3. 【撤】用 git 回滚(代码)或 os.replace 放回备份(数据/产物)
4. 【复核】逐项核对,不能只看"看起来回来了":
       · 代码:git status 干净 + 文件行数/字节数与原版一致
       · 产物:页数 / 图数 / 字节数(本项目实测口径:1 页 / 13 图 / 229504 字节)
5. 【记录】把"为什么撤"写进文档或 commit 消息(否则下次会重走一遍)
6. 【重跑门禁】回滚后必须再跑一次 --selftest / --smoke(撤的过程本身可能出错)

回滚不等于"白干":判据 5 那几次的经验都被写成了设计稿/截图/状态文档 —— 方案不成立本身就是最有价值的知识(它省掉了后面所有人的一次尝试)。


反模式

❌ 半成品"留着反正没坏"

半成品会退化已发布效果(用户看到的是"以前好的现在不好了")。 它也不会自己变好,只会让下一个人以为"这是有意的设计"。

❌ 回滚不记录

下次还会有人提同样的方案、走同样的弯路。"为什么不成立"必须写下来。

❌ "不改"不写理由

"不改"如果没有理由,就会被当成"没做"而反复重提。 (对照:本项目每次"不改"都带当时的数字 + 触发条件。)

❌ 在错误架构上打第 4 个补丁

第 4 个补丁的复杂度不是加法的,是乘法的(要考虑前三个的相互作用)。 到这一步应该回架构层:要么重写、要么回滚重来。

❌ 回滚后不验证

撤的过程本身可能出错(文件没覆盖全、os.replace 目标不对、备份本身已坏)。 必须逐字节 / 逐项复核,并重跑门禁。

❌ 把"来不及"当"不用回滚"的理由

时间压力是当时的处境,不是质量判据。 门禁红 + 会退步时,"先留着"的代价会在验收/线上加倍返还。

❌ 验收打回后回到"实现"而不是"侦察"

验收打回往往意味着前提错了,而不是"实现有小 bug"。 直接改实现 = 在没搞清症状的情况下动手。


边界

能判(客观)

  • 门禁是否红(退出码)
  • 是否退化已发布效果(对照产物 / 断言)
  • 补丁次数(可数)
  • 是否动过用户数据(可查)

不能判(主观)

  • "更优"有时是观感判断 ⇒ 需要数字或 A/B 图来支撑,否则只能交人裁决
  • 两个方案都说得通时取哪个 ⇒ 通常是"改动更小 / 更不易退化"的那个

需要人工裁决


一句话

门禁红 + 会退步 ⇒ 立刻回滚;调研证明不改更优 ⇒ 留档不改;同一架构补丁过三 ⇒ 停下重想。


回滚是需要**主动承认"这条路不对"**的动作——藏起来的半成品会一直退化已发布效果。

判据 3 说"同一架构上补丁 > 3 次就停下"。但真正难的是识别**"我改错了层",而不是数补丁个数。 出现下列任一信号,说明问题不在你正在改的这一层**:

  1. 换到第 3 种同类写法还没成(3 个正则 / 3 个包裹位置 / 3 个 if 分支)——同一层内的表达变化已经用完了, 继续换写法的期望收益趋零。
  2. 补丁必须靠"保护性前置"才能不崩(加白名单、加哨兵、加"遇到 X 就跳过")—— 你的补丁在对抗下游的既有契约,而不是在满足它。
  3. 修完指标反而更差(残留从 2 涨到 8、通过率下降)——立刻回退,不要叠加。

停下来之后做一件事:写出这条链路的阶段契约(输入是什么、谁在哪个阶段做切分/转换、输出形态是什么), 把"我以为它在 A 层"换成"实测它在 B 层"。层找对了,通常只需要一处改动。

幂等性自检(文本/结构变换的必检项)

任何"替换 / 包裹 / 转义 / 规范化"变换,先问一句:同一份输入跑两遍,结果会不会变?

  • 会变 ⇒ 你的变换不幂等,迟早二次包裹($$…$$ 外层再套一层、转义符翻倍)。
  • 判据:f(f(x)) == f(x),且要在真实语料上验证,不是构造样例。
  • 实现要点:不要用"本行有没有标记"判断是否已处理,要用跨行状态(累计的开关/深度/括号配对)。

实战案例与复盘

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

  • 另有两次同类但更小的撤销:卡片 H 的"放宽判据"候选(会破坏卡片 42 的 6 条反例 ⇒ 不做,见设计稿 §3.3 与 bbe6a00)、

  • 以及卡片 M 的第一版修复(按 493.23 钳制后仍越界 6.00pt ⇒ 当轮改正为 481.23,081ab05)。

    • 取舍权:涉及已发布效果与用户可见观感时,最终由人定
    • 是否接受"已知代价"换取收益(如卡片 L 接受"单字母字号不一致")
  • | 1 | 回滚 | 集题本切片器重写(run 扫描 + 事后回填)架构错误 ⇒ 回滚到卡片 46b,只留设计稿 | 回滚点 23b6a5e("卡片 46b:剥无环境片段行首的 &");后来的重写实现是 9d8c85f | docs/design/卡片46c-切片器tokenizer重写.md 首行原话:"DSH 上一次 46c 实现(run 扫描 + 事后回填)架构错误,已回滚(HEAD 回到 23b6a5e 卡片 46b)。本稿只做设计,不含实现。" |
  • | 2 | 回滚 | 集题本"重做"尝试(现场试做后明显更差:矩阵散成行内小图、2 页) | 276baa7(截图:集题本重做尝试,方案不成立,已回滚) | 设计稿 §3.3.5:os.replace 放回备份 ⇒ 复核 1 页 / 13 图 / 229504 字节,与备份逐字节一致 |

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.