This directory contains all the decisions we've made for this starter template and serves as a record for whenever we wonder why certain decisions were made.
Documenting these decisions provides insight into the thought process and tradeoffs considered when building the Epic Stack. The documents explain the context around a decision, what choice was made, and what the implications are.
Decisions in here are never final. As new information emerges or requirements change, previous decisions may need revisiting. However, these documents should serve as a good way for someone to come up to speed on why certain decisions were made originally.
Having this decisions log makes it easier for contributors to understand the rationale behind the codebase, rather than just wondering "why did they do it that way?" It also helps ensure decisions are well-considered, since the process of writing out a decision document forces critical thinking.
Over time, these decision records create a knowledge base full of architectural insights and lessons learned while building the Epic Stack. New contributors can reference past decisions to avoid repeating previous mistakes and build on proven solutions.
So when you encounter an questionable choice in the codebase, consult the decision docs first before assuming there was no rationale behind it! Chances are, there is an entry explaining exactly why it was done that way.