Decisions¶
The decision log holds what was decided, why, and what was considered and rejected. Write one when a choice will constrain later work, especially work by another agent.
| Field | Required | Meaning |
|---|---|---|
id |
yes | Short, stable slug; also the file name |
title |
yes | The decision in a few words |
status |
yes | accepted, or superseded once replaced |
decision |
yes | What was decided |
reasons |
yes | Why, one entry per reason |
alternatives |
no | {"option": …, "rejected": …} for each option not taken |
refs |
no | INIT-… and RMI-… IDs it belongs to or constrains |
roles |
no | Roles it binds; empty means all |
repositories |
no | Repositories it constrains, so an agent can find the decisions that apply to its code |
supersedes / supersededBy |
no | Links to the decisions it replaces or that replaced it; both sides must agree |
Rules:
- Append-only. Never rewrite a decision's substance. Replace it with a
new decision that lists it in
supersedes, and set the old one'sstatustosupersededand itssupersededBy. - No dates. When a decision was made comes from git history.
- No duplication. If a decision is already recorded in an ADR or a spec's PLAN, reference that initiative instead of restating it, unless agents outside that repository need to find it.
Example¶
{
"id": "stewards-not-owners",
"title": "Repositories have stewards, not owners",
"status": "accepted",
"decision": "Several roles may change a repository; at most one stewards it and settles conflicts.",
"reasons": [
"Work crosses repositories, and one role per repository does not scale."
],
"alternatives": [
{"option": "One owning role per repository", "rejected": "Forces every cross-repository change through a message."}
],
"roles": ["billing", "website"],
"repositories": ["github.com/example/web"],
"supersedes": ["one-steward-per-repository"]
}
Validation¶
Decision.Validate checks one decision; ValidateDecisions checks the log:
- IDs are unique slugs, and each file is named after its decision
title,decisionand at least one reason are present- an accepted decision has no
supersededBy; a superseded one has it refsareINIT-<SLUG>-NNNorRMI-<SLUG>-NNN, and repositories aregithub.com/<org>/<repo>rolesname existing rolessupersedesandsupersededByagree on both sides