Part 12 of 12 – Conversation Intelligence Platform series Back to Part 1
There’s a category of engineering problem that doesn’t show up in postmortems or sprint reviews: the slow accumulation of undocumented decisions. Nobody documents the decision in the moment because the context is obvious – everyone involved knows why. Some time later, that context is gone, and someone makes the same mistake again, or undoes something that was done deliberately, or spends days rediscovering reasoning that exists somewhere in a Slack thread from years ago.
I actively monitor our developer Slack channels. It’s not unusual to see someone “fixing” something that is apparently obviously wrong and very much was done that way for a reason – a reason that would have been right in front of them if it had been recorded anywhere. In our case, “some time later” can mean twenty years later. The decisions made in the early days of the platform are still embedded in the codebase, often with no trail left to explain why. This is a cost that compounds, quietly, for as long as the product lives.
Architecture Decision Records (ADRs) are the tool the Simwood engineering team now uses to stop that accumulation.
An ADR is a short structured document that records a decision: what was decided, what the alternatives were, what the reasoning was, and what the follow-on questions are. Written at the time the decision is made. Stored in the codebase alongside the code it relates to. Never deleted – only superseded, with a link to the successor.
This might sound like bureaucracy. It is not. A well-written ADR takes perhaps twenty minutes to produce. In return, it gives any future engineer the ability to understand why the codebase looks the way it does. The auth model uses ForwardAuth claims injection for a specific reason – documented in an ADR. The Keycloak migration is being done via bulk import rather than on-demand provisioning for a specific reason – documented in an ADR. These decisions exist. Without ADRs, they exist only in memory. With ADRs, they’re searchable.
ADRs are internal. They contain implementation details, open questions, and reasoning that isn’t relevant to API consumers. They’re not published at docs.simwood.com; they live in the internal platform docs repository, alongside architecture briefs and service guides that are equally internal.
The simwood-docs MCP (Model Context Protocol) server makes this internal documentation queryable by AI agents working on the Simwood codebase. When an AI is helping an engineer work on a service, it can consult the ADRs directly rather than working from first principles or from assumptions about what might have been intended. “Is there a recorded decision about how API key revocation is handled?” should have an answer, not require trawling Slack history or asking whoever was there at the time.
This is a specific, practical consequence of documentation-first development. The investment in writing good ADRs pays off here in a concrete, immediate way: the AI can reason about decisions that have been recorded, and it can flag when it encounters something that appears inconsistent with a recorded decision. It’s also why Part 2 describes AI as integrated into the development process rather than just assistive – the documentation is the context that makes that integration work.
There’s an onboarding benefit too. When a new engineer joins and asks “why does the auth model work this way?” – the answer should not be “ask Charles.” The answer should be: “Read this ADR.” That’s it. Question answered, without involving anyone else’s time.
The discipline of recording decisions as they’re made is not natural. Most engineers find it easier to get on with building. What Charles and his team have demonstrated is that the upfront investment – writing the brief before the code, recording the decision before moving on – pays back quickly and compounds over time. The codebase is more navigable. The AI assistance is more accurate. New team members get productive faster. The institutional knowledge that would otherwise walk out the door when someone leaves is preserved in a form that stays.
The template for adding a new service – the checklist, the ADR format, the guide structure – also lives in the internal docs. Which means the process of adding a new service is itself documented, followable without asking anyone, and improvable over time.
This is the last post in the series. If you’ve read all twelve, you now understand something that I think matters: the platform isn’t just the Conversation Intelligence features, and the features aren’t just code. They’re the product of a process – documented before it was built, AI-integrated throughout, decisions recorded so they can be found – that we think is genuinely better than how most engineering is done. We’ll find out whether that’s right over the next decade.
For now: the platform is live, the docs are real, and the APIs work. If you’re building on it, we want to hear how it goes.
