Gap
#44, #46 and #48 cover the YAGNI standard, over-engineering as the sixth review dimension, and prevention at plan/implementation time. All three are judgement-based: someone decides, by reading the code, whether a piece of machinery is needed.
That judgement is exactly what fails. The author's local justification for a guard, a parameter or a fallback almost always holds up on its own terms — which is why over-engineering survives review even when reviewers are looking for it.
What actually settles it
Necessity is an empirical question. Delete the thing, run the verification, see what happens.
This was used ad-hoc across a six-PR cleanup and repeatedly beat reasoning:
- A Puppet manifest's
timeout => 1800 looked like defensive padding over Puppet's 300s default. A real build applied its catalog in 301 seconds. Load-bearing, by one second, and no amount of reading the manifest would have established that.
GOPRIVATE / GIT_CONFIG_GLOBAL looked redundant next to an already-redirected HOME. Removing them fails the private-module fetch.- Conversely, ~15 lines of idempotence machinery had a completely coherent local justification and guarded a state the calling system cannot reach. It came out with no effect on anything.
The part worth writing down
"Nothing broke" has two possible meanings, and conflating them is how a coverage gap gets mistaken for dead code:
- the code was genuinely unnecessary; or
- the verification is too weak to notice.
If deleting a guard that protects a real invariant breaks no test, the honest finding is "this guard is untested" — not "this guard is unnecessary". Those cases point straight at the hole that let the risk in, and are usually worth more than the deletion would have been.
Proposed
- A "Deletion probes" subsection under "Verifying a Refactor" in
coding-standards.md: the loop, the two readings of a clean run, restore-between-probes, one probe at a time.
- Wire it into the three phases in
CLAUDE.md — plan (state what breaks without each non-obvious item), implementation (probe your own additions before review), and the over-engineering review dimension (probe rather than argue when necessity is contested).
Gap
#44, #46 and #48 cover the YAGNI standard, over-engineering as the sixth review dimension, and prevention at plan/implementation time. All three are judgement-based: someone decides, by reading the code, whether a piece of machinery is needed.
That judgement is exactly what fails. The author's local justification for a guard, a parameter or a fallback almost always holds up on its own terms — which is why over-engineering survives review even when reviewers are looking for it.
What actually settles it
Necessity is an empirical question. Delete the thing, run the verification, see what happens.
This was used ad-hoc across a six-PR cleanup and repeatedly beat reasoning:
timeout => 1800looked like defensive padding over Puppet's 300s default. A real build applied its catalog in 301 seconds. Load-bearing, by one second, and no amount of reading the manifest would have established that.GOPRIVATE/GIT_CONFIG_GLOBALlooked redundant next to an already-redirectedHOME. Removing them fails the private-module fetch.The part worth writing down
"Nothing broke" has two possible meanings, and conflating them is how a coverage gap gets mistaken for dead code:
If deleting a guard that protects a real invariant breaks no test, the honest finding is "this guard is untested" — not "this guard is unnecessary". Those cases point straight at the hole that let the risk in, and are usually worth more than the deletion would have been.
Proposed
coding-standards.md: the loop, the two readings of a clean run, restore-between-probes, one probe at a time.CLAUDE.md— plan (state what breaks without each non-obvious item), implementation (probe your own additions before review), and the over-engineering review dimension (probe rather than argue when necessity is contested).