| name | architecture-audit |
| description | Systematic architecture review workflow. Use before major feature work on an unfamiliar or inherited codebase, before scaling milestones, or as a periodic health check. Maps the system as-built (not as-documented), dispatches parallel specialist reviews, and produces an evidence-backed findings report with severity verdicts. |
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
