Architecture Drift Audit

Everyone has an opinion about which file is the problem. Opinions cluster on whatever someone touched most recently, which is not the same as whatever costs the most. An audit is worth running only if it produces a ranking somebody would act on, and that means measuring rather than reading.

The contract

This skill reports. It does not edit. Not the trivial fixes, not the obviously dead export. The output is a ranked list; acting on it is a separate decision. An audit that quietly changes the code it is auditing cannot be trusted to have been honest about what it found.

1. Inventory

• Every source file, its line count, and its language.
• The import graph. Use the ecosystem's own tool where one exists — madge or dpdm for JS and TS, go list -deps, pydeps or grimp for Python. Hand-rolled regex over import lines misses dynamic and re-exported edges and will understate the problem.
• Twelve months of history: git log --numstat --since='12 months ago' gives commits and changed lines per file.

2. Measure

• Size — files over the budget, functions over the budget.
• Fan-in — how many modules import this one. High fan-in is not itself bad; it is the multiplier on everything else.
• Fan-out — how many modules this one imports. High fan-out with high fan-in is a god module.
• Cycles — import cycles, reported as the full loop rather than a single edge.
• Boundary violations — feature packages importing siblings, domain code importing framework code, anything importing a test helper.
• Dead exports — exported and never imported anywhere. Check dynamic access and framework conventions before believing it; a route file's default export has no importer by design.
• Duplication — clusters of near-identical logic. jscpd or equivalent; report the cluster, not every pair.

3. Rank by blast radius

Sort by fan-in × churn, not by size.

A 900-line file that nothing imports and nobody has edited since 2023 is not urgent, whatever its line count. A 200-line module that forty files import and someone edits weekly is where the cost actually is: every change to it risks forty consumers, and changes are frequent. That product is the ranking column. Size is a tiebreak.

4. Report

One table, highest blast radius first:

| # | File | Finding | Fan-in | Commits/yr | Lines | Score |

Then, for the top five only, a short paragraph each: what the module has accumulated, which boundary it breaks, and what the smallest useful first move would be. Do not write a paragraph for all sixty findings — nobody reads past the fifth.

Write it to docs/architecture-audit-<YYYY-MM-DD>.md so the next run can report drift as a delta: what got worse, what got better, what is new.

5. Only if asked, a fix plan

Sequenced so each step is independently mergeable — a plan whose value arrives only at step nine will be abandoned at step three. For each step: the change, the blast radius, how to verify behaviour is unchanged, and roughly how long it takes.

Order by ratio of cost removed to risk taken. Extracting a pure helper out of a god module is cheap and safe; re-drawing a feature boundary is neither, and goes later.

Judgement calls

• A big file is not automatically a problem. A 700-line generated client, a lookup table, an exhaustive switch — these are fine. Rank by cost, and say plainly when a large file is healthy.
• Do not recommend splitting to hit a number. Splitting a cohesive module to satisfy a line budget makes the code worse and the metric better. Say so if the budget is the only argument.
• Framework conventions are not violations. Next.js route files, Django settings, Nest modules have structural requirements. Learn them before reporting them as drift.

Verification gate

• The import graph came from a real dependency tool, not a regex over import lines.
• Churn figures came from git log, with the window stated in the report.
• Every dead-export finding was checked against dynamic access and framework conventions.
• Ranking is by fan-in × churn, and the report says so, so the reader can disagree with the metric.
• Nothing was edited.
• Paste the commands used so the run is reproducible.