make-decision-doc

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

1. Read the existing files under decisions/ (e.g. decisions/001-*.md) to match tone and structure.
2. Pick the next number by counting existing files (ls decisions/ | wc -l) and add 1. Filename is NNN-kebab-slug.md with a 3-digit zero-padded prefix.
3. Pick a slug that names the thing being decided, not the verb (single-matcher, not pick-single-matcher).
4. Draft the doc following the structure below. Keep it grounded — no hypothetical alternatives, no aspirational language.
5. If the decision relates to other decisions, link them as footnotes ([NNN]: ./NNN-other.md).

Structure

No rigid template — match the style of existing docs. The shape that tends to work:

• H1 title: a short statement or question that a reader scanning the folder can grok at a glance.
• Opening framing (1–3 short paragraphs): what the choice was, why it came up, and what the realistic alternatives were. Lead with concrete context, not abstractions.
• Tradeoff sections: typically "What gets simpler / harder", "Why we chose X", or named sections per dimension (perf, complexity, ergonomics). Use H2s.
• When to revisit (optional but encouraged): a numbered list of conditions that would flip the decision. Keeps the doc honest and gives future contributors a clear off-ramp.
• Footnote links to related decisions or external sources cited in the body.

Content rules

• Ground every claim. Cite benchmarks, blog posts, code references, or measured behavior. If the decision is "feels nicer", say so explicitly rather than dressing it up.
• Only list alternatives that were actually deliberated. Inventing options to knock down weakens the doc.
• Past tense for the decision ("we chose X"), present tense for ongoing implications ("X means we don't need Y").
• Keep prose tight. These docs reward density — readers come looking for a specific answer.
• Code references use the repo's standard path/to/file.ts style; line ranges with backtick fences when illustrating a specific snippet.
• No marketing tone, no hedging filler ("it's worth noting that…", "in many cases…"). State the call.

Checklist

• Did you read at least one existing decision doc to match style?
• Is the filename NNN-kebab-slug.md with the next available number?
• Does the H1 communicate the decision in one line?
• Are the alternatives ones that were actually considered?
• Did you cite concrete evidence (benchmarks, sources, code) instead of assertions?
• Is there a "when to revisit" section if the decision could plausibly flip?