Architecture Audit

The Law

AN ARCHITECTURE CLAIM WITHOUT A FILE REFERENCE IS AN OPINION.
"The service layer is tightly coupled" is not a finding.
"OrderService imports 14 concrete classes from 6 modules (src/services/order.ts:1-22),
so a payment-provider swap requires touching all 6" is a finding.

When to Use

• Before major feature work on an inherited or unfamiliar codebase
• Before a scaling milestone (10× users, new region, new platform)
• After rapid growth phases where structure was sacrificed for speed
• As a periodic health check on long-lived systems
• NOT for greenfield design — use the architect agent and brainstorming skill instead

Audit Workflow

Step 1: Map the System As-Built

Document what the code actually does, not what the docs or diagrams claim. Read entry points, build files, and dependency manifests before any source.

## System Map — YYYY-MM-DD

**Entry points:** (servers, CLIs, cron jobs, queue consumers — with file paths)
**Modules/layers:** (as they exist in the folder structure, not the intended design)
**External dependencies:** (databases, queues, third-party APIs — where each is called from)
**Data flow:** (request → response path for the 2-3 most important operations)
**Trust boundaries:** (where unvalidated input enters, where auth is checked)

If the as-built map contradicts existing architecture docs, record every divergence — each one is a finding.

Step 2: Identify Load-Bearing Decisions

List the architectural decisions the system depends on, whether or not anyone made them deliberately:

Step 3: Dispatch Parallel Specialist Reviews

Use the dispatching-parallel-agents skill. Each specialist gets the Step 1 system map plus a scoped question:

Skip a specialist only if their domain is absent (e.g., no database → no database-reviewer).

Step 4: Consolidate Findings with Evidence

Every finding must carry a file reference and a consequence:

## Finding N: <one-line statement>

**Evidence:** `path/to/file.ts:12-40` — <what the code shows>
**Consequence:** <what breaks, slows, or blocks because of this>
**Effort to fix:** S / M / L
**Risk if unfixed:** <concrete scenario, not "tech debt">

Findings without evidence are deleted, not softened.

Step 5: Classify Severity

Step 6: Verdict and Report

## Architecture Audit — YYYY-MM-DD

**Scope:** <what was audited>
**System map:** (Step 1 output)
**Findings:** N critical / N high / N medium / N low
**Verdict:** SOUND | SOUND-WITH-RISKS | INTERVENTION-REQUIRED

**Top 3 actions:** (ordered by risk-to-effort ratio)

Feed CRITICAL and HIGH findings into the writing-plans skill as remediation plans. Record accepted risks as ADRs via the architect agent so the next audit can check whether the risk materialised.

Rationalization Red Flags

• "The architecture is fine, the team just needs to be careful" — change amplification is structural, not behavioural
• "We'll audit after this next feature ships" — the next feature is built on the unaudited structure
• "The diagram in the wiki shows clean layers" — audit the code, not the diagram