NNNN. Decision stated as a short sentence
- Status: proposed
- Date: YYYY-MM-DD
Copy this file to NNNN-short-slug.md, take the next free number, and replace every section below. Keep the whole record short, because a record nobody finishes is a record nobody consults. Status is one of proposed, accepted, rejected, or superseded by NNNN.
Context
Section titled “Context”Describe the situation that forced a choice. State the constraint, not the solution: what the repository needs, what makes the obvious answer insufficient, what was already true before anyone proposed anything. Name the alternatives that were weighed and say why each was rejected, one sentence apiece. Alternatives with no stated reason for rejection read as alternatives nobody considered, and they will be proposed again.
Decision
Section titled “Decision”State what is decided, in the present tense, as a rule the repository follows. Be specific enough that a reader can tell whether a given piece of code obeys it. Where a tool enforces the decision, name the command or the configuration key that does the enforcing. But where it is convention only, say so plainly, so nobody assumes a lane is watching.
Consequences
Section titled “Consequences”Say what the repository pays and what it gains. Include the costs that are permanent, the work the decision creates elsewhere, and the gaps it leaves open. Every Consequences section with only benefits in it is unfinished. State known gaps as honest descriptions of the current shape, not as items to be fixed later. Records are not backlogs.