Skip to content

The decision records

Each design decision of this kit is an architecture decision record, an ADR. An ADR is a short file that gives the context of a decision, the decision, and its consequences. I keep them in the repository so that a contributor can read the reason for a rule without access to a private tracker. A code comment gives its reason inline, or it cites an ADR.

The ADRs are in docs/adr/. They record decisions about the whole kit, so they sit in the documentation and not inside one skill. The site does not build them as pages. This page is the index, and each entry links to the file on GitHub. A test fails when an ADR exists that this page does not list, so the index cannot fall behind.

The index

How to read an ADR

Each ADR opens with a status, a date and the part of the kit that it applies to. The date matters. A harness fact in an ADR is true on the day I measured it, and a new version of the harness can change it. When a decision depends on such a fact, the ADR names the version and the date.

Some ADRs set limits that come up again in the enforcement model and its limits. ADR 0002, ADR 0005 and ADR 0007 do.

How to add an ADR

Write the next number, a short name, and the sections Context, Decision and Consequences. Then add the ADR to the index above. The test names the ADR that is missing from the index.

Version main