Architecture-Doc Freshness Audit Against Live IaC

Tier: Core · Hands-on time: ~25 minutes

Stale documentation is a documented contributor to incident pain: responders trust a doc, the doc lies about the system, and minutes become hours. Architects own a specific slice of that risk — the HLDs, decision records, and onboarding docs that describe system structure — and IaC gives that slice a mechanical freshness oracle. Where pb-08 diffs one diagram against the Terraform, this playbook audits the whole prose corpus: every claim a document makes about deployed structure, checked against what the code says is deployed, with fixes delivered as reviewable PRs rather than a report nobody actions.

When to use

• •
  Quarterly doc hygiene, or before an audit/ARB where stale docs become findings against you.
• •
  After a significant infrastructure change lands, to catch every document that described the old world.
• •
  Onboarding feedback says the docs lie — new joiners are the freshness alarm nobody instruments.

Skip AI when there is no IaC to audit against — with a ClickOps estate the oracle is missing, and this becomes a manual review with the console open.

Prerequisites

• Claude Code (or comparable repo-aware agent) with read access to both the docs (repo or export) and the infrastructure repo.
• Docs in or near the repodocs-as-code makes this playbook native; wiki-hosted docs need an export first (and the fix path becomes wiki edits, not PRs).
• A recent terraform show or plan output for deployed truth where .tf files alone are ambiguous — reviewed for secrets before the agent sees it.
• A git branch for the fix PRs.

The workflow

1. 1.

   Inventory the checkable claims. Have the agent build the audit surface first: "Read docs/ and list every factual claim about deployed infrastructure — services in use, counts, regions, engine versions, network paths, resource names — as a table: claim, verbatim quote, document + section, and the IaC evidence that could verify it. Skip aspirational/roadmap statements and design rationale." Separating checkable claims from intent is the step that keeps the audit honest — an ADR's "we chose X because" is history, not staleness, even if X is gone.

2. 2.

   Verify claim-by-claim against the IaC.

   Copy

   For each claim in the inventory, check it against infra/ (Terraform)
   and the provided terraform show output. Verdict per claim:
   - CURRENT: IaC confirms it (cite resource addresses).
   - STALE: IaC contradicts it (cite the contradicting resource and
     state what is actually deployed).
   - GONE: the described component has no corresponding resource.
   - UNVERIFIABLE: the claim is about something IaC does not capture
     (manual config, SaaS settings, process) — do not guess.
   Produce the freshness report grouped by document, worst-first, with
   a one-line proposed correction for every STALE and GONE item.
   

3. 3.

   Confirm the findings before fixing anything. Spot-check every GONE and the high-impact STALEs against the console or terraform state list — the agent may have missed a module, a second repo, or a resource managed by a different workspace. A "correction" that deletes documentation of a real, live component is the audit failing in the dangerous direction: the doc was right and the audit made it wrong.

4. 4.

   Triage UNVERIFIABLE honestly. These are claims about the parts of the system IaC cannot see. Each gets a human owner check or an explicit tag in the doc ("manual configuration — last verified [date]"). The worst outcome is silently treating unverifiable as current; the tag converts unknown freshness into visible, dated freshness.

5. 5.

   Fix via small PRs, grouped by document. Have the agent draft the corrections: "For docs/hld-order-flow.md, apply the proposed corrections from the report. Change only sentences the report flagged; preserve voice and structure; one commit per document." Small, per-document PRs get reviewed; a 40-file doc-sync mega-PR gets approved unread, which re-poisons the well. Route each PR to the document's owner, with the relevant report rows in the description.

6. 6.

   Schedule it and instrument the trend. Wire the audit to run on a cadence (quarterly, or triggered by large infra/ merges). Track one number over time: stale-claims-found per run. Falling means docs-as-code discipline is taking; rising means infrastructure is outrunning documentation and the practice, not the tooling, needs attention. Sameer runs this monthly across the GCC's landing-zone docs and reports the trend line to the platform steering meeting.

Verify before you trust it

• Resource citations open. Every STALE/GONE verdict cites Terraform addresses — spot-check that they exist and mean what the report says. The agent inferring absence from a failed grep is the false-positive engine here.
• Deployed truth was actually consulted. If the audit ran on .tf files alone, module indirection and workspace variables can hide resources; confirm the high-stakes verdicts against terraform show output or the console before PRs merge.
• Corrections corrected, not deleted. Review PR diffs for the lazy fix — removing the stale sentence instead of stating the current truth. A doc that no longer mentions the database is fresher and worse.
• No secret leakage in the loop. State and show output can carry sensitive values; confirm what the agent was given was sanitized, and that no PR diff quotes a secret into documentation.

Restricted-environment variant

Both corpora — client docs and client IaC — are MSA-governed. Run the agent inside the approved boundary: Claude Code on the client's Bedrock/Azure OpenAI tenancy, or a local model over cloned repos where egress is prohibited. The deterministic fallback preserves most of the value when no AI may read the estate: script the claim inventory as a grep for service names and resource identifiers in docs, diff that lexicon against terraform state list output, and review the mismatches by hand — the agent adds prose understanding, but the freshness oracle is the IaC either way. Fix PRs flow through the client's normal review process, whoever drafted them.