This module turns AI loose on the architect's written record — ADRs drafted and red-teamed in hours, decisions mined out of Slack archaeology, docs that stay consistent with reality, a knowledge base that cites or refuses — and on the elevator ride between engine room and penthouse that Hohpe calls the architect's real job.
Phase-1 research puts AI-for-documentation adoption around 61%, and nowhere does that land harder than on architecture's written record: ADRs, HLDs, knowledge bases, pre-reads, and the three versions of every story you tell upward, sideways, and downward. The leverage is real — documentation debt is mostly a production-cost problem, and AI removes the production cost. The discipline is equally real: a decision record whose decision came from a model, or a knowledge-base answer with no citation, is worse than the tribal knowledge it replaced, because it looks authoritative.
Vikram, Enterprise Architect at a BFSI firm, is preparing Thursday's ARB session. On the agenda: a new lending-analytics platform whose design proposes a different relational engine than the org's Aurora standard. The team's pre-read asks, reasonably: "Why is Aurora the standard? We can't find a decision record."
Neither can Vikram. The org's ADR log starts eighteen months ago; the Aurora choice predates it. The reasoning exists — he was in the room — but the record is nowhere.
He points an ADR-mining pass at organizational memory: exported Slack threads from the platform channel, two wiki pages, and the PR discussions from the original migration repo. The prompt asks for implicit decisions — options considered, the choice, the drivers, who decided, with links to the source messages.
The mining pass surfaces a year-old Slack thread: a three-day discussion comparing the candidate engines, ending in a decision driven by cross-region replication behavior during a regional failover test and a licensing constraint on the alternative. Names, dates, even a benchmark screenshot. The Aurora decision, reconstructed with citations.
Vikram drafts the retroactive ADR from the mined evidence, marks it retroactive — reconstructed from sources, validated by participants, and sends it to two engineers from the original thread, who confirm and correct one detail.
He runs the ARB prep pass: AI generates the pre-read pack for Thursday and — querying the knowledge base of past review findings — simulates the six objections this board is most likely to raise against the new proposal, including the one the retroactive ADR now answers directly.
The ARB meets. The "why Aurora?" challenge comes up in minute five. The answer is a linked ADR with sources, not an appeal to memory. The board spends its hour on the actual novel question — whether the analytics workload's replication needs genuinely differ — instead of relitigating history.
Two workflows carried that week: decisions mined out of organizational memory into validated records, and meeting preparation that anticipates objections instead of absorbing them live. Both run on the same rule as everything in this track — AI drafts and retrieves with citations; humans validate and decide.
Drafting (UC-16). The ADR is the architecture artifact best matched to AI assistance, because its skeleton is standardized (MADR-style: context, options considered, decision, consequences) and its raw material — the design discussion — already exists as notes, transcripts, or threads. The working pattern: feed the discussion to the assistant, get back a scaffolded draft with the options laid out and consequences enumerated, then do the human part — confirm the decision statement is actually the decision that was made, in your words, with the drivers you'd defend. Keep a house template in a persistent workspace so every ADR lands in the same shape; consistency is what makes a decision log queryable later. The division-of-labor rule from Module 1 applies verbatim: AI structures options and consequences; the decision and its rationale are signed by a human.
Mining (UC-17). Most organizations' most important decisions predate their ADR practice — they live in Slack threads, wiki edits, and PR review arguments, exactly where Vikram found the Aurora decision. The mining workflow runs an LLM over exports of those sources with instructions to surface implicit decisions: recurring "we chose X because" patterns, closed debates, standards asserted without a record. Three rules keep it honest:
Red-teaming (UC-11 applied to decisions). Before a high-stakes ADR ships — a platform standard, an irreversible data-store choice — run an adversarial pass against the record itself:
You are a hostile future reader of this ADR: an architect five years from
now, cleaning up the consequences. Attack the record, not the prose style.
[ADR pasted]
1. Which options were plausibly available but not considered?
2. Which stated drivers are assumptions in disguise — and which would
change the decision if they proved false?
3. What does this decision make expensive later (exit costs, lock-in,
skill dependencies)? Are those consequences stated?
4. Under what future conditions should this decision be revisited? Does
the ADR name them?
5. What would a regulator or auditor ask that this record can't answer?
Do not rewrite the ADR. Return findings with severity; I decide what
changes.
The output improves the record while the decision is still cheap to adjust — and the findings you reject are worth appending as "considered and dismissed," because the hostile future reader will raise them again. Lab 03 grades exactly this loop: five ADRs drafted from a transcript, one red-teamed, with the before/after as the artifact.
AI removes the production cost of a disciplined decision log — drafting, mining, and red-teaming at speed — but a record is only authoritative when its decision is human-made, its sources are linked, and its reconstructions are labeled and validated.
A decision log and design docs decay in two ways, and long-context AI is well matched to both.
Internal consistency (UC-18). An HLD assembled from ADRs, diagrams, and requirements accumulates contradictions: the diagram shows a queue the text never mentions, section 3 promises an RTO section 7's design can't meet, terminology drifts between authors. Cross-checking a long document for contradictions is a genuine LLM strength — feed the full HLD (with diagram sources as code, which is why Module 2's diagrams-as-code practice pays off here) and ask specifically for contradictions between sections and between text and diagrams, each with both locations cited. You adjudicate which side of each contradiction is right; the model must not "fix" the document, because picking the winning side is a design decision. The human signs the doc.
Freshness against reality (UC-19). The second decay is drift from the live system: docs describing services that were replaced, SKUs that changed, components that no longer exist. The audit pass runs a repo-aware assistant over the docs and the live IaC/state together — the same comparison discipline as Module 2's diagram drift check, extended to prose — and flags stale references with citations to the IaC that contradicts them. Fixes go out as reviewable PRs against the docs, not silent edits. Run it on a schedule; stale-doc failure is documented in incident literature precisely because nobody notices drift until the wrong doc is trusted during an incident.
The compounding asset (UC-21): embed the ADRs, HLDs, and review findings, and put a retrieval interface in front of them, so "why did we pick Aurora?" or "what's our standard for queues?" is a thirty-second self-serve answer instead of a senior architect interrupt. This is Common Core RAG applied to your own record, with two properties that are non-negotiable in an architecture context:
The refusal behavior is enforced in the response contract, not hoped for in the prompt:
from pydantic import BaseModel
from typing import Literal
import anthropic
class KBAnswer(BaseModel):
status: Literal["answered", "not_in_corpus"]
answer: str # empty when not_in_corpus
citations: list[str] # ADR ids / doc sections; empty ⇒ must refuse
confidence_note: str
client = anthropic.Anthropic()
def ask_kb(question: str, retrieved_chunks: list[str]) -> KBAnswer:
resp = client.messages.parse(
model="claude-opus-4-8",
max_tokens=2000,
thinking={"type": "adaptive"},
system=(
"Answer ONLY from the retrieved excerpts of our ADRs and design "
"docs. Every claim must cite an excerpt. If the excerpts do not "
"contain the answer, set status=not_in_corpus and do not "
"speculate — an invented org standard is a defect."
),
messages=[{
"role": "user",
"content": f"Question: {question}\n\nExcerpts:\n" + "\n---\n".join(retrieved_chunks),
}],
output_format=KBAnswer,
)
return resp.parsed_output
An answer with citations empty and status "answered" is rejected by the calling code — the contract makes uncited authority structurally impossible rather than merely discouraged. Vikram's ARB week ran on this base twice: the mined Aurora ADR made "why Aurora?" answerable, and the objection-anticipation pass queried past review findings through the same interface.
A knowledge base that answers confidently from outside its corpus converts tribal knowledge into fabricated policy — build refusal-on-unknown into the response schema and reject uncited answers in code, not in hope.
Gregor Hohpe's framing: the architect's differentiating skill is riding the elevator between the penthouse, where business strategy lives, and the engine room, where implementation lives — and translating faithfully in both directions. The skill was always scarce because each ride costs production effort: the same decision needs a board one-pager, an engineering-leadership deck, and a build-team brief, and most architects only ever produce the version for the floor they're most comfortable on. AI removes the production cost (UC-35/36); what it cannot remove is the consistency obligation — three renderings of one decision must remain the same decision.
| Altitude | Audience | Form | What changes | What must not change |
|---|---|---|---|---|
| Penthouse | Board / executives | One-pager | Vocabulary: cost, risk, time-to-market; numbers traced to the verified cost model | The decision, its drivers, its stated risks |
| Mid-floor | Engineering leadership | Short deck | Trade-offs, team and roadmap impact, migration path | Same |
| Engine room | Build team | Working brief | Interfaces, constraints, ADR links, the first two sprints | Same |
The workflow: write the canonical decision record first (the ADR), generate the three renderings from it, then run an AI consistency check across the three — same decision, same drivers, same risk posture, no altitude quietly promising what another altitude ruled out. The exec one-pager's numbers trace to the verified cost model, never to model recall — Module 1's rule, at penthouse stakes. Lab 15 grades this whole pack: one AI-platform decision, three altitudes, plus the consistency report.
For India-based architects presenting to US/EU stakeholders, the elevator pack is also a timezone instrument: a pre-read that survives an async review across nine time zones must anticipate the questions a live presenter would catch in the room — which is the next workflow.
Build the objection-anticipation pass from your own ARB's past findings, not generic best practice — boards are creatures of habit, and last year's findings predict this year's objections with embarrassing accuracy.
The architect's record becomes an asset when every decision is written, mined, or red-teamed into a cited, validated log — and the same decision rides the elevator to every altitude without changing shape.
Two labs anchor this stage. Lab 03 — ADR factory with a red-team pass: draft five ADRs from a design-discussion transcript, red-team one high-stakes record, revise; the artifact is the five ADRs plus the before/after of the attacked decision. Lab 15 — The architect elevator pack: one AI-platform decision rendered as board one-pager, engineering-leadership deck, and build-team brief, with an AI consistency check across the three.
Companion playbooks: pb-14 (ADR Drafting with an Options-Analysis Scaffold), pb-15 (ADR Mining from Slack, Wikis & PR History), pb-16 (HLD Consistency Checking — Diagram Says X, Text Says Y), pb-17 (Architecture-Doc Freshness Audit Against Live IaC), pb-18 (Architecture Knowledge Base — RAG over ADRs & Designs), pb-19 (Exec One-Pagers & the Three-Altitude Pack), and pb-20 (ARB Pre-Reads, Objection Anticipation & Workshop Synthesis).