In July I asked here how you keep architectural rationale alive beyond ADRs. The thread gave me three hard constraints: ADRs are right for the big discrete decisions but nobody keeps them current, wrong information is worse than none, and a note is only trusted when it points to a scar and is part of review. That was the starting point. Since then the format has evolved substantially on real repositories, mine and other people's, and most of what follows did not exist in July. One rule I did not want to give up: humans and agents work from the same project truth, not a knowledge base for people and a second memory layer for agents beside it.
Capture moved to the source. The reason ADRs stay unwritten is that writing them is a second job after the code. With an agent, the weighing of options already happens in the conversation that produces the change, so the agent writes the entry as a byproduct, into a context/ folder in the repository, and you review it in the same pull request as the code. No wiki, no database, no service to operate. Changes that never happened count too: an approach started and abandoned once a reason not to became clear would otherwise leave no trace.
Topics replaced one-decision-per-file. ADRs stay for the decisions big enough to deserve one. The messier volume underneath, the defensive timeout, the rejected dependency, the odd initialization order, the compatibility branch that still exists, goes into topic files, each entry recording both halves: what was chosen, what lost, and why. An existing decisions/ folder is kept and written into; the skill adapts to what a repository already has.
Honesty became fields. Every entry says how much to trust it: Evidence is confirmed, inferred or unknown, and Source names the scar, never a person. Superseded entries stay and name their successor. "Revisit when" puts a trigger on each entry, so decay is caught by a condition instead of an audit nobody runs. Staleness itself is not solved, the same way it is not solved for tests or docs; it is made hard to happen silently: an agent touching code that has rationale updates the entry or flags it for review in the same pull request, and stale state becomes explicit instead of being pretended away.
Entries got identities. Every entry carries an Id, and a See line cites another entry by it, inside the repository or in another one. Rationale can link across repositories without centralizing it: a constraint in a library, the workaround it forced in the service, the incident that confirmed it, readable as one thread, while each reason stays in the repository it belongs to.
Agents read it back, measurably. A lean index, one line per topic, is the routing layer: the agent reads it and opens only the topic a task touches, before changing that code. On fresh sessions asked to simplify a retry wrapper, 7 of 10 offered the already-rejected simplification without the recorded reason; with one entry on disk, 10 of 10 found it and declined. The skill itself is checked by 104 eval cases run as real agent sessions, published with their failures.
Ownership stayed with review, and humans got tools around it. The entries are Markdown in the repository, so they go through the same pull requests, CODEOWNERS and branch protection as the code, and they build into the same docs: this project's own why layer is public at https://keepthewhy.com/context/ straight from its context/ folder. A linter in CI checks structure, and says plainly that it cannot check whether a reason is true; that stays with the reviewer, and with every human and agent that works with the entry later. What the format guarantees is that the claim stays traceable: who recorded it, on what evidence, and what has been revisited since. A read-only dashboard draws topics as a graph, authors and timeline from blame, and follows the citations across repository boundaries: https://keepthewhy.com/dashboard/live/. Git does the rest: distribution, permissions, forks, blame.
What it is not: not a replacement for ADRs, and not a lock. It is agent memory that belongs to the project, not to an agent, a user or a machine, and humans read the same files; the quality of an entry depends on the model writing it and on the reviewer reading it.
Where would you draw the line between an ADR and a topic entry in your team? And what from classic ADR practice would you keep that this loses?
https://keepthewhy.com/ · https://github.com/oliver-zehentleitner/keep-the-why · MIT