principle-fix-root-causes

修根因

When debugging, do not fix symptoms. Trace every problem to its root cause and fix it there.

调试时别修症状。把每个问题追到根因，在那里修。

Why: Symptom fixes accumulate. Each workaround makes the system harder to reason about, and the real bug remains. Root-cause fixes are slower upfront but reduce total debugging time.

为什么： 症状修复会堆积。每个 workaround 都让系统更难推理，真 bug 还在。根因修复前期更慢，但总调试时间更少。

Pattern:

模式：

• Reproduce first

• Ask “why” until you hit the root cause

• Do not add guards (adding a nil check to silence a crash is a symptom fix)

• If a workaround needs a paragraph-long comment to justify it, the code is wrong (fix the code, not the comment)

• Check for the pattern, not just the instance (grep for the same pattern, fix all instances)

• When stuck, instrument. Don’t guess (add logging, read the actual error)

• 先复现

• 追问「为什么」直到根因

• 别加守卫（加 nil 检查捂住崩溃是症状修复）

• workaround 需要一整段注释才能说圆，说明代码错了（修代码，别修注释）

• 查模式，不只查这一例（grep 同模式，修全部实例）

• 卡住就埋点，别猜（加日志，读真实错误）

Restart bugs: suspect state before code

重启类 bug：先怀疑状态，再怀疑代码

When something “fails after restart,” suspect stale persistent state first: config files, caches, lock files, serialized state. If clearing a state file restores behavior, prioritize state validation as the fix.

「重启后失败」时，先怀疑陈旧持久状态：配置、缓存、锁文件、序列化状态。清状态文件就恢复，就把状态校验当优先修复。