Good "why" documentation can sometimes be fairly localized though. ADRs are great for overarching design "whys", but are not really the best tool for highly loc

Good "why" documentation can sometimes be fairly localized though. ADRs are great for overarching design "whys", but are not really the best tool for highly localized "why" documentation. For example: sometimes you may have a codebase where whenever "X" is done, there is an automatic retry mechanism of failure. But then you have one spot where there is no automatic retry. And it turns out there is a very subtle and non-obvious reason why an automatic retry here would be a problem. The code then deserves a comment explaining what this subtle issue is, and and why it means automatic retries must be avoided here. Without such a comment, the next person to touch the code may well just assume the automatic retrying was forgotten, and add it, causing say the painful data corruption bug to return.