Most knowledge management programmes ask people to maintain a repository for its own sake, which is why they stall. This post explains a different mechanism: align the map with what solution architects are already measured on, make improving it incremental, and let the effects compound. It is the capstone of the conversion how-to series and builds on the philosophy in shaping enterprise context by design and architecture knowledge management versus document knowledge bases.
Why do architecture knowledge programmes stall?
Because the person asked to maintain the knowledge is not the person who benefits from it. A repository is treated as an obligation, so upkeep competes with delivery and loses. Exhortation, mandates, and annual clean-ups do not change that incentive; they only make the decay slower to notice.
What do solution architects actually need?
Solution architects are judged on artefacts: decision records, blueprints, diagrams, and review packs that move a change forward. They do not get credit for a tidy repository. That is not a flaw to fix; it is a lever. If the quickest route to a good artefact runs through the map, curation stops being extra work.
Why does every blueprint need landscape context?
A blueprint that ignores neighbouring systems, integrations, owners, constraints, and prior decisions describes a change in a vacuum. It cannot be costed, reviewed, or safely delivered. Landscape context is what turns a design into an assessable proposal — and rebuilding that context for each piece of work is the Context Tax.
Generating artefacts from curated context is covered in how to generate ADRs, blueprints, and diagrams from living architecture context. The flywheel is what makes that capability self-reinforcing.
How does the flywheel turn?
- An artefact is needed — an ADR, blueprint, or assessment for a real change.
- It needs landscape context — the bounded slice the change touches.
- Incremental modelling fills the gaps — AI proposes missing or outdated entities and relationships from new evidence; the architect corrects the ones that matter.
- The map improves — accepted changes persist, so the next artefact in the same area starts further ahead.
Nobody is asked to “update the repository”. They are asked to produce the artefact, and the map improves because that is the fastest way to do it.
Why is incremental modelling the enabling piece?
A flywheel needs low friction at every turn. If improving the map means a large modelling exercise, the loop never starts. Incremental modelling keeps each step small:
- Start from whatever documents and spreadsheets already exist.
- Add evidence for a bounded domain; the model extends rather than restarts.
- Review a short queue of proposals tied to the work in hand.
- Leave the rest as it is — coverage grows where it is needed, not uniformly.
See the incremental modelling documentation for how the workflow runs, and keeping the repository up to date with AI curation for the operating cadence.
What can a graph find that no document knows?
A single document holds only the connections its author knew. A curated graph holds connections that appear when several sources are read together: one document names a queue, another names the service publishing to it, an inventory row ties that service to a platform, and a decision record mentions the platform’s retirement. No document says “this retirement affects those consumers”, but the graph can — and AI can recommend the missing edges for review.
The agent side of this is described in what AI does inside an Architecture Decision Workspace.
How does this support an agentic SDLC?
Coding, infrastructure, test, and change agents ask landscape questions at far higher frequency than people do. If each one crawls ungoverned documents, you multiply the Context Tax and speed becomes drift. A curated map gives them a shared, cited context plane. The flywheel keeps that plane current as a side effect of ordinary architecture work. See architecture context for agentic SDLC.
How do you shape context by design instead of by accident?
- Choose the metamodel deliberately — typed entities and relationships that match the questions you need answered.
- Bind evidence to claims — keep the How and Why with the entity, not in a separate wiki.
- Curate with accountability — a named steward per domain, not a shared inbox.
- Make the map the default source — artefacts, reviews, and agent context all start there.
How does DecisionPen solve this?
DecisionPen is an Architecture Decision Workspace designed so that the work solution architects already do improves the map.
- Incremental modelling from documents and spreadsheets, extending the map rather than rebuilding it.
- Generated artefacts — ADRs, blueprints, and diagram images built from curated context, so correcting the map is the fastest way to a better artefact.
- Graph recommendations that propose connections across sources for human review.
- Enterprise Ask and agent-ready context that reuse the same curated map.
Trial DecisionPen by producing one blueprint for a real change, then a second in the same area, and compare how much context you had to rebuild.
When is DecisionPen not the right tool?
If nobody will curate the map, a flywheel will not start. If the real need is a freeform drawing canvas, generic document search, or live infrastructure scanning, DecisionPen is the wrong fit. It compounds curated architecture context; it does not replace ownership or discovery scanners.
What to read next
- Shaping enterprise context for IT knowledge management
- Architecture knowledge management vs document knowledge bases
- What does AI do inside an Architecture Decision Workspace?
- How do you generate ADRs, blueprints, and diagrams?
- Architecture context for agentic SDLC
- Incremental modelling
Series index (Conversion how-tos)
- D8a — Fast-track M&A IT due diligence
- D8b — Build application dependency maps from documentation
- D8c — Assess a landscape without months of workshops
- D8d — Keep the repository up to date with AI curation
- D8e — This post (the incremental modelling flywheel)