Why your AI code auditor should be able to tell you how it's wrong
A docstring told me the write was safe. So did the architecture doc. Both had been reviewed; both had been trusted. They described a liveness update — the kind that flips a record to "in progress" — and they were specific about the guard: the write, they said, was conditional on the record's status, so a finished record could never be re-opened by a late, racing writer. Compare-and-swap, in the filter. Textbook.
The code matched the record by its id. Only its id. The status predicate the docs promised wasn't there.
Nothing was on fire. In practice there was effectively one writer, so the race the missing guard would have allowed had never been provoked. But the guard the documentation described — the one a future maintainer would read, trust, and then decline to add because "it's already handled" — did not exist. The doc wasn't stale. It had never been true. And it was confident enough that no reviewer had thought to check it against the single line of code it claimed to describe.
I didn't find that by reading carefully. I found it because I'd built a tool whose entire job is to assume a confident claim is guilty until reconciled against reality — and to tell me, in the same breath, how it could be wrong about that.
