architecture-audit

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:

Decision	Where visible	Deliberate or accidental?
Monolith vs services	repo layout, deploy config
Sync vs async processing	queue usage, HTTP call chains
Data ownership	which modules write which tables
Coupling direction	import graph between layers
State management	session stores, caches, singletons

Step 3: Dispatch Parallel Specialist Reviews

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

Agent	Scoped question
architect	Do module boundaries and coupling direction support the next 12 months of planned work?
security-reviewer	Are trust boundaries enforced at every entry point in the system map?
performance-profiler	Which architectural choices (N+1 patterns, sync chains, missing caches) cap throughput?
database-reviewer	Does data ownership match module boundaries? Any schema shared by unrelated modules?
infra-reviewer	Does the deploy topology match the code topology? Any single points of failure?

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

Severity	Criteria	Action
CRITICAL	Data loss, security boundary bypass, or scaling wall within one milestone	Block feature work until addressed
HIGH	Change amplification — routine features require touching 3+ modules	Schedule before next major feature
MEDIUM	Coupling or duplication that slows work but doesn't block it	Backlog with owner
LOW	Style-level structure issues	Note only

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)

Verdict	Criteria
SOUND	No critical or high findings — proceed with planned work
SOUND-WITH-RISKS	High findings exist with agreed mitigation dates
INTERVENTION-REQUIRED	Any critical finding — architecture work precedes feature work

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