| name | make-decision-doc |
| description | Add a numbered decision document under `decisions/` to capture a non-obvious architectural choice. Use when the user asks for a decision doc, ADR, design rationale, or wants to record why we picked one approach over alternatives. |
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
- Read the existing files under
decisions/ (e.g. decisions/001-*.md) to match tone and structure.
- 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.
- Pick a slug that names the thing being decided, not the verb (
single-matcher, not pick-single-matcher).
- Draft the doc following the structure below. Keep it grounded — no hypothetical alternatives, no aspirational language.
- 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?
