You keep EA factsheets current by letting AI do the two jobs people skip: drafting per-entity descriptions from the context you already hold, and recommending relationships that no single document states. Humans then curate both. The result is a map whose entries explain themselves and whose edges keep evolving as new evidence arrives — instead of a repository of thin, blank, or year-old factsheets.
Why do factsheets go stale or stay thin?
A factsheet needs a clear description, correct relationships, and enough rationale to be useful. Writing those by hand for hundreds of entities is a poor use of an architect’s week, so the work is deferred. The outcome is familiar: names without meaning, links that were true at workshop time, and the How/Why living elsewhere (why EA factsheets miss the How and Why). Training people to fill in fields harder does not fix the economics.
How can AI generate an entity description from context?
A description generated from the entity’s own context beats a generic summary. The inputs are bound evidence (design documents, notes, inventory rows), the entity’s type under the metamodel, and its existing relationships. The output is a short, reviewable description: what it is, what it is for, where it sits.
- Gather — the entity’s evidence passages and its neighbours in the map.
- Draft — a concise description in the organisation’s style, grounded in those sources.
- Show provenance — which documents informed which statements.
- Curate — accept, edit, or reject; accepted text becomes part of the Context of Record.
This is the per-entity counterpart to enriching factsheets with unstructured documents: enrichment pulls facts in; description generation turns them into something a reader understands in seconds.
What are relation recommendations?
A relation recommendation is a proposed edge between two entities — for example “application A integrates with application B” or “this service supports that capability” — together with the evidence that suggests it. It is a candidate, not a fact, until a human accepts it.
- Typed — proposals respect the metamodel, so a capability does not “integrate with” a vendor by accident.
- Evidenced — each suggestion cites the passage or record that prompted it.
- Ranked — stronger, corroborated suggestions surface before weak ones, so curation time goes where it counts.
- Reversible — rejected suggestions are remembered so they do not keep returning.
Why do some graph edges appear in no single document?
Many of the most useful relationships are implied across sources. One design document names a queue; another names the service that publishes to it; an inventory row ties the service to a platform; a decision record mentions the platform’s retirement. No document states “the retirement affects this queue’s consumers,” but the graph can, once the intermediate edges exist.
This is why per-document summarisation does not substitute for a map: summaries stay inside document boundaries; relation recommendations cross them.
How do connections evolve over time?
Landscapes change continuously. New evidence should be able to extend, confirm, or contradict existing edges:
- Extend — a new design adds integrations to an existing application.
- Confirm — a second source corroborates a prior edge, raising confidence.
- Contradict — a newer source conflicts with the map, producing a review item rather than a silent overwrite.
- Retire — a decommissioning decision updates status and flags affected neighbours.
That cadence is what incremental modelling means in practice: small, evidence-driven curation steps that compound, rather than annual re-baselining. It also feeds deep reasoning — the better the edges, the better the answers from agents interrogating the map.
How do you keep humans in control?
- Treat every description and relation as a proposal with evidence.
- Review by queue, prioritising high-impact entities and strongly evidenced edges.
- Measure outcomes: description coverage, accepted-versus-rejected recommendation rates, and edges added per week.
- Keep ownership with the architecture steward; do not auto-publish.
How does DecisionPen solve this?
DecisionPen is an Architecture Decision Workspace that treats factsheet upkeep as a continuous, assisted process rather than a data-entry project (see incremental modelling).
- AI descriptions generated per entity from bound evidence and map context, with provenance.
- Relation recommendations that propose typed, evidence-backed edges across documents and sources.
- Human curation — accept, edit, reject, or defer; nothing becomes authority without review.
- Living map — accepted updates feed Enterprise Ask and generated artefacts, so upkeep pays back immediately.
Trial DecisionPen on one domain of thin factsheets: review the generated descriptions and the top recommended relations, and count how many connections your team had not recorded.
When is DecisionPen not the right tool?
If you want fully unattended, auto-published factsheets with no human review, or only a runtime asset inventory, or a drawing canvas. DecisionPen proposes descriptions and relationships for curation; it is not an autonomous scanner of live infrastructure and does not remove the need for an accountable steward.
What to read next
- Why EA factsheets miss the How and Why
- How do you enrich EA factsheets with unstructured documents?
- How do AI agents deep-reason over an EA map?
- How do you generate ADRs, blueprints, and diagrams?
- Incremental modelling
Series index (AI in the Architecture Decision Workspace)
- D7a — What AI does inside an Architecture Decision Workspace
- D7b — Model EA from structured and unstructured sources with AI
- D7c — Review and curate AI-proposed architecture models
- D7d — ADRs, blueprints, and diagrams from context
- D7e — Agents interrogate and deep-reason over the map
- D7f — This post (descriptions and relation recommendations)