That's a great point. I can be less diligant in my documentation than i'd like to be at times. This means somethimes the "why" of something isnt discussed. I need to stop doing that and find a way to add all the "whys" without overwhelming readers who just want answers. Maybe footnotes or appendicies.

While I appreciate the effort and strive to do so myself, I’m not sure this is entirely a matter of you trying harder/doing better. You can often explain the context well enough to a degree that is practical enough to solve the narrow case, but communication is lossy by nature, so descriptions of systems become impoverished. It is so hard not to make bad assumptions about the reader, especially if you look forward even 1 or 2 generations from now. It seems this is a large part of the role of the US Supreme Court and I’m certain that is not perfect even with days of deliberation. For technically enforced systems with faster feedback loops, higher volumes, and lower tolerances, there are necessarily more errors.