Besluiten vastleggen als besluitrecords

Context en probleemstelling

Een atlas die architecten en agents samen bijhouden, verandert voortdurend. Wie een uitspraak leest, moet kunnen nagaan of zij besloten is, door wie en waarom, en welke alternatieven zijn afgewogen. Zonder vaste vorm verdwijnen die afwegingen in pull requests en gesprekken.

Beslisfactoren

• Herleidbaar: een vaste plek voor context, opties, afweging en gevolgen.
• Machinaal te controleren: status, datum, beslissers en de uitspraken waarop het besluit werkt.
• Leesbaar zonder eigen gereedschap, ook buiten GitHub.
• Klein te houden: een eenvoudig besluit gebruikt alleen de verplichte koppen.

Overwogen opties

1. MADR 4.0 in de atlas — ieder besluit als concept van type Besluitrecord in kennis/adr/.
2. Besluiten alleen in pull requests — de beschrijving van de pull request is het besluit.
3. Een besluitenlijst per domein — een tabel in het domeinconcept.

Besluit

Gekozen optie: “MADR 4.0 in de atlas”, omdat alleen die vorm opties, afweging en gevolgen vastlegt en tegelijk als concept door de validator te controleren is.

• Een besluit heet kennis/adr/<nnnn>-<naam>.md en ADR-<nnnn>; de nummers lopen op.
• De status is voorgesteld, aanvaard, afgewezen, vervallen of vervangen. Een aanvaard besluit verandert niet meer; een nieuw besluit vervangt het (vervangt, vervangen_door).
• Een vastgestelde of vervallen uitspraak noemt in besluit het besluit waarop zij rust. Een besluit noemt in uitspraken welke uitspraken het vaststelt of laat vervallen.
• Alleen een architect aanvaardt: door de pull request goed te keuren. Na het samenvoegen zet de workflow de status op aanvaard en legt de beslisser vast.

Gevolgen

• Goed: iedere vastgestelde kennis is te herleiden tot een besluit met een afweging.
• Goed: de site toont per besluit wat het vaststelt, en per uitspraak op welk besluit zij rust.
• Slecht: ook een klein besluit vraagt een eigen bestand; het minimale sjabloon houdt dat licht.