Decisions With an Approver and No Date

Documentation is software. It has authors, versions, dependencies and defects; it rots when its dependencies move; and the difference between documentation that survives and documentation that becomes actively misleading is almost entirely a question of what metadata it carries. Most teams treat the ADR as a writing exercise and stop at the prose. The prose is the easy half.

Part 14 found architecture drift you could read in one line of C#. This part reads the records — four ADRs, three checked-in diagrams, a Miro board and a README — as artefacts with their own lifecycle, and asks what would happen to each of them a year after the last commit.

What the records get right

Start with the credit, because there is a lot of it and this series' final grade depends on it.

Four real ADRs sit in architecture-decisions/, plus an empty template. Each of the four opens with two lines:

**Zgłaszający:** Michał Wilczyński

**Zatwierdzający:** Dariusz Pawlukiewicz

Reporter and approver. Not “author”. The second name is the thing most decision records never have, and its presence changes what the document is: not one person's write-up but a decision two people held at once, with accountability attached to both roles. I have reviewed a great many ADRs and I would guess fewer than one in five names an approver.

The structure is consistent across all four — Context, Considered options, Decision, Expected outcome, Links — and it is inherited from 00-szablon.md, the template, which ships in the repository authored by the Polish equivalent of John Smith. A template checked into the repository is itself an architectural artefact: it makes “write an ADR” a two-minute task rather than a blank-page task, which is the entire difference between a team that has three decision records and a team that has none.

The content honours the structure too. ADR 01 lists two options for module communication and three for enforcement, picks one of each with a stated reason, and names its own upgrade trigger. ADR 04 gives the losing option a genuine advantage and the winning option two genuine costs. ADR 02's links section points at a dotnet/runtime issue predicting that .NET 8 would ship an equivalent of the IClock abstraction it recommends. These are not rubber stamps.

Three architecture images are checked in beside them: the context map, the Postsale context map crop, and a Domain Message Flow diagram with twelve numbered messages across a “FLOW OF TIME” divider. They are referenced from ADR prose by relative path, so they travel with the repository and appear in the rendered markdown on GitHub. That is the right call — a diagram in a wiki is a diagram that will be orphaned.

The metadata that is missing

Now the gaps, and every one of them is a field rather than a paragraph.

No dates. Not one of the four ADRs records when the decision was taken. In most repositories you would recover this from git, and here you cannot: the history is three commits, of which 2473c13 Init landed all thirty-five projects and all four ADRs at once. The two later commits change a community link in the README. There is no meaningful git blame on any decision in this repository — every line of every ADR has the same authorship stamp as every line of Program.cs.

That matters more than it sounds. An ADR's value decays, and the reader's only defence is knowing the vintage. “We chose a verbal prohibition because there are few developers” is excellent reasoning in month one and a question in year three. Without a date, a reader cannot tell whether they are reading a current position or an archaeological find, and the decision quietly acquires an authority it was never given. A decision record with no date reads as permanent, which is the opposite of what a decision record is.

No status, no supersession. There is no Status: Accepted line, no mechanism for one ADR to supersede another, and no place to record that a decision has expired. ADR 01 explicitly names the condition under which it should be revisited — when more developers join, move to the reflection-based architecture test — and there is nowhere to write down that the condition has been met. The upgrade trigger exists in prose and has no landing site.

No linkage to the code. ADR 04 describes ten steps of a change process; part 10 scored them and found nine implemented, but that scoring took me an afternoon of reading. Nothing in the repository connects step 7 to the handler that implements it, and consequently nothing notices that step 7 is wired to the wrong event. An ADR that names a file, a test or a namespace gives the next reader a hook; this one names none.

The board that lives outside version control

The README's third paragraph, translated: A supplement to this repository is a public board on Miro, with an image linking to domain-driven-design.net/miro.

Read the direction of that sentence carefully. The board is a supplement to the repository — the repository is the primary artefact and the board is the annex. That is the healthier of the two framings, and it is not the usual one; most estates I have seen have it the other way round, with the wiki as the source of truth and the code as an implementation of it.

But the board still holds the discovery work — the event storming, the subdomain distillation, the TO-BE modelling that the README lists as the process this repository is the result of. Which means the artefacts that produced the eight modules live at a URL, under a third-party account, with no version, no diff, and no relationship to any commit. If Miro changes its sharing model, or the account lapses, or somebody drags a sticky note, nothing in the repository knows.

And the cost shows up immediately in one file. ADR 03's ## Linki section, in its entirety, is one word:

## Linki

Miro

Not a URL. The word “Miro”. A reader who wants the reasoning behind the context map — the map whose three unbuilt boxes were part 5 — gets a noun. This is the failure mode of split-brain documentation in its purest form: the writer knew what they meant, the two halves lived in different tools, and the reference degraded to a gesture.

If architecture lives outside version control, the repository must at minimum record the address. A URL costs nothing and survives the writer.

The links that will rot

The README does one more thing that is worth naming precisely, because it is a genuinely good instinct with a known decay curve. Four of its design bullets link into the source by file path, and two of them link by line number:

• The naive access control bullet points at EndpointRegistration.cs#L17. Line 17 today is public enum NaiveAccessControl — exact.
• The JSON-persistence bullet points at OfferRepository.cs#L31. Line 31 today is the AddAsync call, two lines above the SerializeToJson invocation the bullet is describing — close, and already not quite the line it means.

Both work right now. Neither will survive a using statement being added at the top of the file, and nothing will report the breakage, because a GitHub line anchor that points somewhere wrong renders identically to one that points somewhere right.

To be fair, the alternative is worse in a different way: a README that describes a mechanism without pointing at it forces the reader to grep. And for a teaching repository whose whole purpose is to be read, a deep link into the exact line is genuinely valuable — I used those links, and they helped. The durable version of the same instinct is to link to a symbol rather than a line: EndpointRegistration.cs plus the type name in the prose. Slightly less precise, immune to insertion.

The five fields I would add

None of this needs a documentation platform, a process, or a meeting. It needs five lines in 00-szablon.md, which is the file the whole estate copies from:

# NN - Title

**Status:** Proposed | Accepted | Superseded by ADR-NN
**Date:** yyyy-mm-dd
**Reporter:** …
**Approver:** …
**Applies to:** src/Sales/…, src/Shared/GroupFlights.Shared.Plumbing/…

Status and Date give the reader the vintage and the standing. Applies to gives the next person a place to look and — if you want the enforcement — a path a test can assert exists. The template already has the two hard fields, the ones that require a human decision about accountability. It is missing the four that require no judgement at all.

The pattern worth taking is that decision records fail on their metadata, not on their prose. Every one of these ADRs is well argued. Every one of them will be harder to trust in three years than it needs to be, for want of a date.

Next, the retrospective: what strategy-first actually bought them.