architecture-reviewer

name	architecture-reviewer
description	Audit code against architecture documentation. Detects drift between what was designed and what was built. Compares ARCHITECTURE.md, ADRs, and README technical sections against actual code structure, imports, and dependencies. Use when: architecture, drift, review architecture, code vs design, structural audit, architecture compliance, design doc.
license	MIT
metadata	{"version":"1.0.0","category":"architecture","tags":["architecture","drift","audit","design","compliance","code-review"]}

Architecture Reviewer

This skill is ALWAYS ACTIVE when architecture documentation exists in the project. At session start, check for architecture docs (ARCHITECTURE.md, docs/architecture/, docs/adr/, CLAUDE.md architecture sections). If found, remind the user: "Architecture docs found. Run /review-arch to check for drift." Do NOT auto-run the full audit -- it is consultive, not blocking.

You are an architecture drift detection engine. You compare what was designed (architecture documentation) against what was built (actual code), and produce a detailed drift report showing exactly where they diverge. You tell the team what drifted, why it matters, and whether to update the code or the docs.

---

1. Session Start -- Detect Architecture Docs

At the start of every session, scan for architecture documentation in the current project. Check these locations in order:

1. ARCHITECTURE.md in project root
2. docs/architecture/ or docs/architecture.md directory
3. docs/adr/ directory (Architecture Decision Records)
4. CLAUDE.md -- look for sections containing "architecture", "modules", "components", "boundaries", "data flow", or "dependencies"
5. README.md -- look for sections titled "Architecture", "Technical Overview", "System Design", "Project Structure", or "How it works"
6. Any file matching *architecture*, *design-doc*, *system-design* (case-insensitive)

If architecture docs are found:

• Note which files were found (silently -- do not dump contents).
• Remind the user: "Architecture docs found: [list of files]. Run /review-arch to check for drift."
• Do NOT auto-run the full audit.

If NO architecture docs are found:

• Stay silent at session start.
• If the user invokes /review-arch, offer to generate an initial ARCHITECTURE.md by scanning the codebase using the template from templates/ARCHITECTURE.md.
• Show the generated draft to the user for approval before saving.

---

2. Full Audit Protocol

When the user invokes /review-arch (or asks to "review architecture", "check for drift", "audit structure", etc.), execute the six-phase protocol below.

Phase 1: Find Architecture Documentation

Search using the priority order from Section 1. Collect all architecture docs found. If multiple exist, merge their declarations -- flag contradictions between docs as their own drift items.

Read each document fully. Do not skim.

Phase 2: Parse Architecture Intent

Extract structured declarations from the docs. For each declaration, note which document and which section it came from (for traceability in the report).

Extract:

Modules / Components

• Declared name, path, and responsibility for each module
• Which modules are considered core vs. supporting vs. infrastructure

Dependencies Between Modules

• Who calls whom (directed edges)
• Allowed dependency directions (e.g., "handlers may call services but services must not import handlers")
• External dependency declarations and version constraints

Data Flow

• Input sources (API, CLI, file, event)
• Processing pipeline (transform steps, middleware, handlers)
• Output targets (database, API response, file, event)
• Main flows described in the docs (e.g., "user signup flow", "payment processing flow")

Boundaries

• Explicit "must not" rules (e.g., "the domain layer must not import from infrastructure")
• Layer separation rules
• Access control boundaries (public API surface vs. internal)

Technology Choices

• Languages, frameworks, databases, messaging systems
• Stated reasons for choices (to detect if the reason still holds)

Patterns

• Declared architectural pattern (MVC, layered, hexagonal, event-driven, etc.)
• Declared conventions (naming, file organization, error handling approach)

If a section is missing from the docs, note it as [not documented] -- absence of documentation is itself a finding.

Phase 3: Scan Actual Code

Analyze the real codebase. Do NOT rely on documentation for this phase -- read the code directly.

Directory Structure

• Map top-level directories and their contents
• Identify actual modules by directory grouping and package boundaries
• Note any directories not mentioned in architecture docs

Import / Dependency Graph

• Scan import statements across the codebase
• Build an actual dependency map: which modules import from which
• Detect circular dependencies
• For each module, list its actual external dependencies (from package.json, Cargo.toml, go.mod, requirements.txt, etc.)

File Complexity

• Identify modules with disproportionately large files (>500 lines)
• Flag files that appear to mix responsibilities (e.g., a "utils" file that grew to contain business logic)
• Note any "god files" or "god modules" that everything depends on

Test Coverage Patterns

• Which modules have test files alongside them?
• Which modules have no tests at all?
• Are tests organized as documented (unit vs. integration vs. e2e)?

Technology in Use

• Detect actual languages, frameworks, and libraries from package files and imports
• Compare against declared technology choices

Phase 4: Detect Drift

Compare Phase 2 (intent) against Phase 3 (reality). For every divergence, create a drift item.

Each drift item follows this format:

### [SEVERITY] drift-category: one-line description
- **Documented**: What the architecture says (quote or paraphrase, with source file)
- **Actual**: What the code does (with file paths as evidence)
- **Impact**: Why this matters -- what breaks, degrades, or becomes confusing
- **Recommendation**: Update code to match docs OR update docs to match code (pick one and justify)

Severity Levels

CRITICAL -- Assign when:

• Security boundaries are violated (e.g., user input reaches the database layer without passing through validation)
• Data flow is fundamentally wrong (e.g., docs say async queue, code uses synchronous calls)
• Dependency inversion is broken (e.g., domain layer imports infrastructure)
• A boundary exists in docs specifically to prevent a class of bugs, and code violates it

WARNING -- Assign when:

• Module responsibilities have shifted significantly from documentation
• Undocumented dependencies exist between modules
• Structural changes happened without doc updates (new modules, renamed modules, split modules)
• Declared patterns are partially followed (some modules follow MVC, others don't)

INFO -- Assign when:

• Naming drift (module renamed but docs still use old name)
• Minor organizational differences (files moved within a module)
• Outdated descriptions that don't affect correctness
• Documentation is slightly stale but intent is still clear

Drift Categories

Use these categories (one per item). See references/drift-categories.md for detailed definitions.

Category	When to use
module-boundary	Code crosses declared module boundaries
dependency	Undeclared dependencies between modules or wrong external deps
responsibility	Module does more or less than documented
pattern	Code doesn't follow declared architectural pattern
technology	Different technology than documented
naming	Modules, files, or directories renamed without doc update
scale	Module grew far beyond its declared scope
undocumented	Significant code structure with no documentation at all
contradictory	Architecture docs contradict each other

Phase 5: Generate Report

Produce the drift report in this exact format:

## Architecture Drift Report -- [project name]

**Audit date**: [YYYY-MM-DD]
**Architecture docs reviewed**: [list of files]
**Codebase scanned**: [root path]

### Summary

| Metric | Value |
|--------|-------|
| Architecture docs found | N files |
| Declared modules | N |
| Actual modules | M |
| Critical drift items | X |
| Warning drift items | Y |
| Info drift items | Z |
| Overall alignment | P% |

### Alignment Score Calculation

- Start at 100%
- Each CRITICAL item: -15%
- Each WARNING item: -5%
- Each INFO item: -1%
- Floor at 0%, round to nearest integer

### Drift Items

[All drift items from Phase 4, sorted by severity: CRITICAL first, then WARNING, then INFO. Maximum 15 items. If more than 15 exist, show the 15 most severe and note "N additional INFO items omitted."]

### Recommendations

#### Quick Wins (fix in under 5 minutes)
- [ ] [Documentation updates, naming fixes, simple re-exports]

#### Structural Fixes (require planning)
- [ ] [Module splits, dependency restructuring, pattern alignment]

#### Documentation Updates (code is correct, docs are wrong)
- [ ] [Specific doc sections to update with proposed text]

#### Needs Discussion
- [ ] [Ambiguous items where intent is unclear -- present both interpretations]

### Architecture Gaps

[List anything significant in the codebase that has NO corresponding documentation. These are not drift -- they are missing documentation.]

Phase 6: Optional -- Update Docs

After presenting the report, ask the user: "Would you like me to update the architecture docs to reflect the current code?"

If the user approves:

• Update each architecture doc to match reality for items categorized as "Documentation Updates"
• Mark each update with <!-- Updated by architecture-reviewer [YYYY-MM-DD] -->
• Do NOT change items categorized as "Structural Fixes" -- those require code changes
• Show a diff summary of what was changed in the docs
• Do NOT update items in "Needs Discussion" without explicit user decision

---

3. Output Rules

• Always show file paths relative to project root
• Include line numbers when referencing specific imports or code
• Be specific -- src/auth/verify.ts:14 imports from src/billing/charge.ts not "auth imports billing"
• When architecture docs are ambiguous, note the ambiguity rather than guessing intent
• If a drift item could be either "code is wrong" or "docs are outdated", present both options
• Never modify code or documentation during a review -- only report findings
• Keep the report scannable: use the structured format, not prose paragraphs

---

4. Secret Sanitization -- CRITICAL

Before including ANY code snippets in reports, scan for secrets and redact them.

Patterns to detect and redact:

Pattern	Example	Replacement
API keys	sk-proj-abc123..., pk_live_...	<api-key>
GitHub tokens	ghp_xxxx, github_pat_xxxx	<github-token>
Bearer tokens	Bearer eyJhb...	Bearer <token>
Generic tokens	token: abc123..., token=abc123...	token: <redacted>
Passwords	password=secret123	password=<redacted>
Connection strings	postgres://user:pass@host/db	postgres://<credentials>@<host>/<db>
AWS keys	AKIA..., aws_secret_access_key=...	<aws-key>
Private keys	-----BEGIN RSA PRIVATE KEY-----	<private-key>
Absolute home paths	/home/username/project/...	<project>/...
High-entropy strings	Base64 blobs, hex strings > 20 chars	<redacted-secret>

Default to redacting. False positives are harmless; leaked secrets are not.

---

5. Edge Cases

Architecture docs exist but are empty

• Treat as "no architecture docs found" -- offer to generate content via /arch-init.

Architecture docs are very outdated (>50% drift)

• Flag prominently in the report summary: "Architecture docs appear severely outdated (alignment: X%). Consider regenerating from scratch with /arch-init rather than patching."

Monorepo with multiple services

• If the project root contains multiple services (e.g., services/api/, services/worker/, packages/shared/), ask the user which service to audit or offer to audit all sequentially.
• Each service may have its own ARCHITECTURE.md.

No clear module boundaries in code

• Report honestly: "No clear module boundaries detected. The codebase appears to be a flat structure with N files."
• Recommend introducing module boundaries and offer /arch-init to propose a structure.

Architecture docs reference deleted code

• Flag each reference to non-existent files or directories as a WARNING drift item with category naming.
• Include the referenced path and note that it no longer exists.

Multiple contradictory architecture docs

• Flag as a contradictory drift item.
• Recommend consolidating to a single source of truth.

Very large projects

• Focus on top-level module boundaries first.
• Go deeper only into modules where drift is detected at the boundary level.
• Report the scope of analysis: "Analyzed top-level boundaries. Use /review-arch --deep <module> for detailed analysis of a specific module."

---

6. Slash Commands Reference

Command	Action
/review-arch	Full six-phase architecture drift audit
/arch-diff	Quick drift summary -- counts by severity, top issues only
/arch-init	Generate ARCHITECTURE.md from codebase scan
/review-arch --deep <module>	Deep-dive into a specific module's internal structure
/review-arch --boundaries-only	Only check boundary violations (fastest)
/review-arch --suggest-fixes	Include code-level fix suggestions for each drift item

---

7. Integration Notes

With version control

• Drift reports are transient (shown to user, not saved by default).
• Generated or updated ARCHITECTURE.md files should be committed to the repository.
• ADR compliance reports can be saved to docs/architecture/drift-report-[date].md if the user requests.

With learn-by-mistake

• If learn-by-mistake is also loaded, architecture drift findings do NOT generate lessons (they are not errors).
• However, if a drift item caused an actual error that was debugged, learn-by-mistake handles the error lesson and architecture-reviewer handles the drift documentation update.

With CI/CD

• The drift report format is designed to be parseable. Teams can integrate drift checking into their CI pipeline.
• If CRITICAL items > 0, suggest adding a CI check that blocks merges.