I follow you.

I do like discussing things after the fact. I think a "proof" is a good starting point, and if you don't start with at least that, then jumping into a slack conversation to do that foundational work causes problems.

I really like a PR as as the place to put the proof: you can only assume it is true for that moment in code, and it is associated with that. Of course it isn't remotely true as all software has bugs, but at least it can be a concise statement of how you understood it at the time, and that's valuable. The author is noting that you need to get into the mental model of the author, and this is a good place to capture your thinking.

I think READMEs for a repository, in general, are almost always worthless and outdated, like you allude to.