architecture-review

name	architecture-review
description	Use when reviewing architecture decisions. C4 model, dependency inversion, hexagonal boundaries.
version	1.0.0
tags	["architecture","review"]

Architecture Review

When to Use

∀ plan reviews (standard, complex). ∀ PRs that touch module boundaries.

Checklist

1. DEPENDENCY DIRECTION: ∀ import: does it follow domain <- app <- infra <- presentation?
2. BOUNDARY CHECK: ∀ new module: is responsibility single and clear?
3. PORT/ADAPTER: ∀ external dependency: accessed through port? adapter exists?
4. COUPLING: ∀ cross-module call: through interface or direct import?
5. ADR: Architecture decision worth recording? -> create ADR

Review Template

Aspect	Status	Finding
Layer dependency	pass/fail	...
Module boundaries	pass/fail	...
Port coverage	pass/fail	...
Cross-cutting concerns	pass/fail	...

Anti-Patterns

• Reviewing code style (that's code-reviewer's job)
• Proposing rewrites for working code (YAGNI)
• ¬reading the spec before reviewing architecture
• Designing for hypothetical future requirements

Rules

• Scope: architecture only, ¬code quality, ¬spec compliance
• ∀ finding: cite specific file + line
• Severity: Critical (blocks) | Important (should fix) | Suggestion (optional)
• ∀ deviation from patterns: justification required

Domain-Vocabulary Heuristics

Apply these structural tests during every architecture review:

Deletion Test

Ask: "If I remove this module, does complexity scatter across the system or consolidate elsewhere?"

• Scatter → the module was hiding distributed complexity. Refactor to make dependencies explicit.
• Consolidate → the module was a genuine abstraction. Keep it.

Thin Implementations

Identify modules with large surface area and low behavioral leverage. These are candidates for deepening — merging, hiding behind a narrower interface, or replacing with a library.

Entangled Units

Locate seams where two modules cannot change independently. One adapter = hypothetical seam. Two adapters = real seam. Entangled units without a seam violate the boundary rule.

Difficult-to-Test Areas

Flag modules that require heavy mocking or complex setup. "The interface is the test surface." Difficult testing often signals a shallow module or a missing port.

Document findings using domain terminology from CONTEXT.md or DOMAIN.md, not generic handler or service names.