A decision is a file of its own, naming the paths it governs and what must not be undone there¶
Decision 790 · accepted · 2026-10-05 · issue #437
Superseded in part
In part by 1025.
- A file per decision.
docs/decisions/<number, four digits>-<slug>.mdfor the repository's,docs/decisions/tui/anddocs/decisions/daemon/for the two that were numbered on their own, which they still are: a number is unique within its directory, andtui/108and108are two decisions, asTUI Decision 108andDecision 108were. A number is reserved for a fixer before work starts, so two pull requests that each decide something add two files and touch nothing in common. - A front matter an agent can scan.
number,title,date,status,pathsandgist, and optionallyissue,pr,supersedesandsymbols.pathsare globs of what the decision governs;gistis at most about 150 characters of what someone changing those paths must not undo, so thatmix troupe.decisions --for <path>(number, gist and file, newest first, a superseded one marked with what replaced it) is enough to decide whether to read the body. The direction is #422's: the decision names the code it governs, and a glob that stops matching fails CI, so a move or a rename breaks the decision's check instead of silently its meaning. - No committed index. The site's index of each log is made by the documentation
site's hook as it builds, from the files' front matter, where the log's README says
<!-- decisions:index -->; in the repository the directory listing is the index. An index the mix task wrote and CI held current would be the one file every pull request that decides something regenerates, and two such pull requests would conflict there, which is the problem this solves. The individual pages are left out of the nav (not_in_nav); the hook gives each its title as the heading, a line of number, status, date and issue, a note naming what superseded it, and the paths it governs. - The check runs on every change, so it needs nothing compiled.
--checkfails on a front matter YAML would read otherwise, a missing field, a number used twice in one log, a missing body, a file name that does not carry the number, or a glob that matches nothing. A glob breaks when any file moves, whatever the change was, so CI runs it inversions, the job that runs on every pull request and checks the documentation's links for the same reason, and not inlint, which runs only when an umbrella app changed: a pull request that only changedclients/vscodewould otherwise add a decision nobody checked. So that a bareelixircan load it there, the task uses no dependency and reads the front matter itself, as the part of YAML a decision is written in, refusing what YAML would read differently from how it looks (an unquoted value with:, a leading backtick, a title YAML would cut at#or read as a number), so that what passes is what MkDocs reads. - Not chosen. Files grouped by area, as #422 first had it: two decisions about one
area would conflict again. An issue per decision: the record would leave the
repository and could not be read offline or reviewed beside its code.
merge=unionin.gitattributes: GitHub's mergeability check and merge button do not use it.
Governs: apps/troupe_protocol/lib/mix/tasks/troupe.decisions.ex, scripts/split-decisions.exs