Skip to content
ritueel

Decision records

A decision record (ADR) says why ritueel is shaped the way it is, what else was weighed, and what follows. The format, the numbering and the status values are in docs/decisions/README.md; the process is in GOVERNANCE.md. This page is the order of work.

The maintainer decides

Section titled “The maintainer decides”

A contributor or an agent presents the options, each with its pros and cons, and a recommendation. It does not pick. The maintainer decides: merging a record with status Accepted is the decision.

From proposal to record

Section titled “From proposal to record”
  1. Proposal. Open an issue with the Decision proposal form: the question, the context, the options with pros and cons, and the options you would not take. The form labels it type:decision.
  2. Record. When the direction is clear, copy the template to docs/decisions/NNNN-short-title-in-kebab-case.md, with the next free number. Link the proposal issue in the context.
  3. Index. Add the record to the index table in docs/decisions/README.md, with its status. Every record has a row, and every row has a record.
  4. Pages. The pages that the decision changes follow in the same pull request, or in the next one (Pages).
  5. Pull request. At most five records per pull request. A larger batch is split.

Accepted means fully decided

Section titled “Accepted means fully decided”

A record is Accepted only when every part of it is decided. While a part is still open, the record stays Proposed, the open part is tracked in an issue, and the record lists it with a link to that issue.

Roads not taken

Section titled “Roads not taken”

Every record keeps the options it did not take: each one with its pros, its cons and why it lost. Git keeps the text that was merged, not the reasoning that was dropped, so this part is required and is never cut to make a record shorter.

Changing a record

Section titled “Changing a record”

Records are append-only. A changed mind gets a new record that supersedes the old one, and the old status line says so (Superseded by NNNN, or Accepted; amended by NNNN). Typos and links may be fixed in place.

What CI checks

Section titled “What CI checks”

CI checks the file name, the required sections, the status value and the index rows; run just check-decisions, then just check, before you push. Passing it is necessary, not sufficient: the maintainer reviews the reasoning.