Make Decision Doc

Overview

Decision docs live at the repo root in decisions/NNN-kebab-name.md. They explain why a choice was made — the tradeoff, the alternatives that were actually considered, and (when useful) the conditions under which we'd revisit. They are not feature specs, not how-to guides, and not changelog entries.

When to write one

• A non-obvious architectural choice was made and a future contributor would reasonably ask "why didn't we do X instead?".
• A choice has tradeoffs that are easy to second-guess without context (perf vs. simplicity, lock-in vs. flexibility, ergonomics vs. correctness).
• We diverged from a common default or industry-standard alternative and the reasoning matters.

Skip a decision doc when the choice is obvious, the alternatives weren't seriously considered, or the rationale already lives in code comments / change file / PR description.

Workflow