Architecture Drift Audit: Make Your Docs True Again

Architecture docs rot one stapled-on paragraph at a time, until new teammates and AI agents follow a map of a system that no longer exists. This skill makes your agent reconcile the docs with the code, using evidence, never vibes.

What it does

• Derives the real module graph mechanically from import statements: type-only imports ignored, re-exports counted, aliases and workspaces resolved. Never taken from prose.
• Classifies every edge: realized, declared-only (documented but not real), undocumented (real but not documented) or forbidden (breaks a stated layering rule), and reports cycles.
• Flags drift with evidence: moved or vanished modules, wrong stack claims, broken layering rules, contradictory doc fragments. Contradictions resolve to what the code shows, not to the newest paragraph.
• Proposes coherent rewrites of each affected section, and applies them only with your go-ahead.
• Scouts cleanup, read-only: unused files, exports, routes, flags and dependencies, plus duplicate logic. Each finding has evidence, confidence, blast radius and the check that would prove removal safe. It writes cleanup briefs only when a campaign crosses an evidence threshold.
• Remembers across runs: standing recommendations with stable IDs, promotion to written conventions after three occurrences, and adoption checks so it never nags about something you already fixed.

How it works

1. Read every architecture doc, prior audit logs and recent git history before writing anything.
2. Build the module registry as the code is now.
3. Compare every doc claim with the code; record findings with path:line or commit evidence.
4. Propose rewrites, scout cleanup, then write the report, ledger and a dated log entry.

Frameworks & tools

TypeScript/JavaScript, Python, Go, Rust, Java/Kotlin and any language with static imports. Works with ARCHITECTURE.md, docs/, ADRs, module READMEs and planning configs.

Why this beats prompting it yourself

Ask an agent to "update the architecture docs" and it rewrites them from what it skimmed, often trusting the docs over the code. This skill derives edges mechanically, separates "does A depend on B" from "is symbol S used" (the most common error in dependency audits), cites evidence for every claim and never deletes code.

Use cases

• Onboard a new engineer or AI agent onto docs that are actually true.
• Find layering violations and dependency cycles.
• Build an evidence-backed dead-code list before a cleanup sprint.
• Fold a big build's scattered changes back into one coherent architecture doc.

Known limitations

Never edits source or deletes anything; cleanup is briefed, not performed. Doc rewrites need your approval. Heavy runtime reflection or string-keyed dependency injection can hide edges from static import analysis; the skill flags these as false-positive risks.