As we speed-run the history of software engineering via trying to make AI coding reliable, repeatable, robust, and resilient...
We sometimes (re)discover something useful for software engineering in general. Checking architectural decision documents, requirements, constraints, and other artefacts in with the code ensures we have the reason for every fence close at hand when we consider removing it, and we have the history of those reasons alongside the code we wrote according to that history.
When I was with GitHub, I championed a product idea nobody wanted: Make GitHub's web editor and support for markup languages so good that we'd have a lightweight but useful alternative to GDocs, PowerPoint, &c.
Then there would be a path for storing docs in the same repo as the code *and* to diff those docs so we could match updates to the docs wth updates to the code.
That's why I put my heart and soul into shipping Rich Prose Diffs: https://github.blog/news-insights/the-library/rendered-prose-diffs/
I had dreams. Or perhaps, madness.
Reginald
Jan D