Ratchets, not ceilings

Defects are not born. They are a function of observation coverage.

Auditing for individual bugs never converges — you find them at the rate you look for them, forever. The only thing that converges is making the class mechanically impossible to grow.

Ceiling vs ratchet

A ceiling says "no more than N." It permits drifting up to N, and someone eventually raises N because "we need to ship."

A ratchet says "no more than the last recorded value, and that value may only ever decrease." Every reduction is locked in. There is no path back up.

# The recorded series. Append-only, strictly decreasing.
_DESCENT = (109, 107, 103)

def test_no_regression():
    current = count_occurrences()
    assert current <= _DESCENT[-1], (
        f"{current} > {_DESCENT[-1]}: this class grew. "
        "Reduce it, or justify a new entry in _DESCENT."
    )

def test_series_is_monotonic():
    assert all(a > b for a, b in zip(_DESCENT, _DESCENT[1:])), (
        "entries must strictly decrease — no raising the bar"
    )

The second test is the important one. Without it, the ratchet is a ceiling with extra steps.

The adoption criterion: retroactive validation

Only adopt a guard that would have caught a bug you already had.

This is the whole filter. Guards invented from imagination test imaginary failures and add maintenance cost forever. Guards derived from real incidents pay for themselves on the first recurrence.

When you write the guard, sabotage the code to make it fail, and put the failure message in the PR. A guard nobody has seen fail is a guard nobody knows works.

Three ways a ratchet gets laundered

1. Definition drift

Narrow what counts, and the number falls without anything improving.

Guard: hash the counting logic itself and store it alongside the count. If the definition changes, the series must fork into a new version — old entries preserved, not overwritten.

_FINGERPRINTS = {"v1": "a3f2…", "v2": "9c81…"}   # hash of the scanner source
_DESCENT_V2 = (60, 47)                            # v1 series kept, not replaced

2. Vocabulary shrink

If the scanner matches on a token list, deleting tokens lowers the count.

Guard: an anchor test that asserts specific known-positive sites are still detected by name. If someone narrows the scanner, the anchors fail.

3. Renaming past the scanner

Rename an intermediate variable and the site stops matching.

Guard: a test that renames a variable in a fixture and asserts the count is unchanged. This one caught a real 30% undercount for me — the scanner was blind to a byte-identical duplicate because of one variable name.

Widening raises the number — that is a finding, not a regression

When you fix a scanner blind spot, the count goes up. It went 46 → 60 for me.

That is not a regression. It is the discovery of prior undercounting. Record it as a new version series with the reason. Do not resist an honest increase because the number looks worse — a number that only ever looks good is not a measurement.

Same logic for exposure: making hidden state visible increases the "unresolved" count. That is the honest value.

Watch for ratchets that punish the right fix

A ratchet counts sites. Consolidating two implementations into one shared helper sometimes adds a site — the new shared function is itself a match.

Check that your counting axis doesn't penalize consolidation, or you've built a machine that blocks the work you want.

(This is also the ratchet working: it caught an implementer writing a duplicate comparison inside new code, and the fix was to extend the canonical function instead. That's the intended outcome.)

Related

• root-cause-discipline — why counting comes before reducing
• blast-radius — mapping the class the ratchet will seal