ADRs need a lifecycle — otherwise agents drown in decisions that are no longer true
I use these skills on a real project (test management app, ~1 year old, solo dev + agents). domain-modeling and triage have been genuinely useful. But I've hit a problem that I think the skills don't have an answer for yet.
We now have 72 ADRs. The skills tell you how to write one. Nothing tells you what happens to it afterwards.
Today I had my agent measure it. The result was worse than I expected:
- 11 of 72 were superseded or rejected — and still sitting in
docs/adr/. So 15% of what an agent reads there is already wrong. - 5 of 7 ADRs marked "Proposed" were actually built and shipped. Nobody had updated the status. So the status field was unreliable in both directions: dead things looked alive, and shipped things looked hypothetical.
- 8 of 59 active ADRs are referenced by nothing at all — no skill, no code comment, nothing.
The cost is two things:
- Tokens. Everything the agent reads, it has to read first. 72 files is not free, and nothing tells it which 3 are relevant to the task at hand.
- Wrong direction. This is the worse one. In one session my agent read an ADR marked "Proposed", concluded the decision had never been built, and reasoned from a picture of the app that hasn't been true for months. The code said otherwise. It only caught it because it happened to check.
That second one is the real problem. A stale ADR is not neutral — it actively points the agent somewhere we're not.
What I think is missing is a lifecycle. Roughly:
- A status that has to reflect reality, and ideally can be checked against the code rather than trusted
- Superseded and rejected ADRs move out of the active folder — they're history, not context
- Some way to see which ADRs nobody references, so you can tell "load-bearing but invisible" from "actually dead"
I'm not asking for fewer ADRs. Writing them down was right. I'm asking that the skill say what happens to a decision after it's written — otherwise the folder just grows, and every agent that opens it pays for decisions that stopped being true a long time ago.
Happy to share what we ended up doing on our side if that's useful.
Source: mattpocock/skills