A stale doc almost outlived what it described

I have a hook that checks whether a session updated its documentation before it finishes. It has caught real problems. It also let a real problem through, and the way it let it through is the more useful story.

The hook’s original test was simple: did this session touch any docs at all. A session could rewrite a whole system, write three unrelated docs about it, and pass clean while a config file loaded into every future session still described the old behavior. Writing some documentation looked exactly like writing the right documentation, and the hook could not tell them apart.

The fix wasn’t a smarter hook. It was a narrower question. Instead of “did docs get touched,” it now asks “did the specific things this session changed get named anywhere they’re already described.” It collects the identifiers a session wrote or deleted, greps every doc that’s supposed to be authoritative, and hands back exactly the files that mention those identifiers and were never opened this session.

It still can’t catch everything. A renamed function or a reworked behavior with no clean identifier attached is invisible to a grep, and that gap is still mine to close by hand. But it turned a check that could be satisfied by accident into one that has to be satisfied on purpose.

The failure mode here wasn’t carelessness. Every session did what it was told: touch docs when you change something. Nobody had asked whether it touched the right ones.