decision-loglisted

# Decision log One file at the repo root, `DECISIONS.md`, with the development decisions that are **not recoverable by reading the code**. Not a changelog. Git already tells you what changed and when, and it does it better than any file a human maintains. What git does not tell you is why the cap is 500 and not 1000, why this model and not the cheaper one, why this approach after the other one was tried and abandoned. That reasoning lives in someone's head, and it leaves when they do. Six months later somebody sees a number with no explanation, assumes it was arbitrary, and changes it. The outage that follows is the cost of not having written one paragraph. ## When to write an entry When you make a decision that **someone could reasonably question later**, and the answer is not visible in the diff. Concretely: - A limit, a threshold, a timeout, a cap. Any number that is not obvious. - Choosing between two viable approaches, when the loser was genuinely viable. - A constraint that comes from outside the code (a platform limit, a provider's pricing, a legal requirement, an ops decision). - Something deliberately **not** done, and why. This is the one people skip and the one that saves the most time: without it, the next person spends a day building what you already ruled out. - A workaround for someone else's bug, with what it works around. Otherwise it looks like clutter and gets cleaned up. ## When not to - The code explains it. If a reader can see why by rea