| name | architecture-review |
| description | Review codebase architecture for SOLID violations, dependency health, module boundaries, and structural issues. Use when assessing whole-system structure or coupling. For single-module depth use /deepening-review; for a concrete refactor plan use /refactoring-guide. |
| user-invocable | true |
| allowed-tools | Read, Grep, Glob |
Architecture Review
Core Rule
Critique module boundaries and dependency health against documented intent. Don't propose rewrites — suggest the smallest seam-cutting change.
When to Use
Invoke with /architecture-review when:
- Evaluating overall project structure and organization
- Planning a major refactoring or migration
- Assessing whether the architecture can support planned features
- Onboarding to a codebase and building a mental model
- Due diligence on an inherited or acquired codebase
Default Behavior
When the user asks to audit, scan, review, or "give me a report" for architecture / module health, produce the full architecture-review report automatically using the Process and Output Format sections below. Do not require the user to specify fields.
Only modify files when the user explicitly requests implement / fix / apply / refactor. By default, this skill is report-only.
Process
Phase 1: Inventory (first-pass leads)
This pass produces candidates, not findings. Treat counts as leads for deeper inspection in later phases. Do not report Phase 1 raw output as the final result.
Build a structural overview:
- Read project config — identify framework, language, dependencies
- Map directory structure — identify layers, modules, boundaries
- Identify entry points — servers, CLI handlers, event processors, main functions
- Trace data flow — request → handler → service → data → response
- Identify patterns — MVC, Clean Architecture, hexagonal, microservices, monolith
Phase 2: SOLID Principles Check
Evaluate adherence to SOLID (adapted for all paradigms):
Single Responsibility (S)
- Does each module/class/file have one clear reason to change?
- Are there god modules that do everything? (>500 lines, multiple concerns)
- Is business logic mixed with infrastructure? (DB queries in handlers, HTTP in services)
Open/Closed (O)
- Can new features be added without modifying existing code?
- Are extension points available? (plugins, middleware, strategy pattern)
- Is there excessive switch/if-else that grows with each feature?
Liskov Substitution (L)
- Do subtypes/implementations honor the contracts of their interfaces?
- Are there interface implementations that throw "not implemented" errors?
- Do overrides change the expected behavior of base methods?
Interface Segregation (I)
- Are interfaces/type contracts focused and minimal?
- Do consumers depend on methods they don't use?
- Are there "fat" interfaces that force empty implementations?
Dependency Inversion (D)
- Do high-level modules depend on abstractions, not concrete implementations?
- Are external services (DB, cache, API clients) behind interfaces?
- Can infrastructure be swapped without changing business logic?
Phase 3: Module Boundaries & Dependencies
Analyze module health:
- Circular dependencies: modules that import each other (directly or transitively)
- Dependency direction: do dependencies flow inward (toward domain) or outward?
- Coupling: changing one module requires changes in many others
- Cohesion: are related concepts grouped together?
- Public surface: are internal details properly encapsulated?
- Barrel exports: do index/barrel files re-export the right things?
Phase 4: Layer Analysis
Check architectural layering:
- Presentation → Business → Data: is the layering consistent?
- Layer violations: does the presentation layer directly access the database?
- Shared state: is mutable state shared across layers?
- Configuration: is config centralized or scattered across modules?
- Cross-cutting concerns: how are logging, auth, validation handled? (middleware, decorators, aspect-oriented)
Phase 5: Scalability Assessment
Evaluate growth readiness:
- Can the codebase support 10x the current feature set without restructuring?
- Are there single points of failure in the architecture?
- Is there a clear strategy for splitting modules if they grow too large?
- Are there hard-coded limits (max items, timeouts) that should be configurable?
Output Format
# Architecture Review Report
## Architecture Overview
[Diagram or description of the current architecture]
[Identified pattern: MVC / Clean / Layered / etc.]
## SOLID Compliance
| Principle | Status | Key Findings |
|-----------|--------|-------------|
| Single Responsibility | ✅/⚠️/❌ | ... |
| Open/Closed | ✅/⚠️/❌ | ... |
| Liskov Substitution | ✅/⚠️/❌ | ... |
| Interface Segregation | ✅/⚠️/❌ | ... |
| Dependency Inversion | ✅/⚠️/❌ | ... |
## Module Health
| Module | Coupling | Cohesion | Issues |
|--------|----------|----------|--------|
## Critical Structural Issues
1. [Issue + impact + recommendation]
## Recommendations
### Short-term (can fix now)
- ...
### Medium-term (next sprint)
- ...
### Long-term (architectural evolution)
- ...
Common Rationalizations
| Rationalization | Reality |
|---|
| "It's just one exception to the architecture" | Exceptions accumulate. Each one makes the next one easier to justify. |
| "We'll refactor when it becomes a problem" | By the time it's a problem, refactoring costs 10x more. Flag it now. |
| "The project is too small for architecture" | Even small projects have structure. Bad habits set early persist at scale. |
| "This coupling is temporary" | Temporary coupling becomes permanent coupling the moment a second feature depends on it. |
| "SOLID is overkill here" | SOLID is a diagnostic tool, not a rulebook. Use it to identify risks, not enforce dogma. |
Notes
- This review focuses on structural architecture, not code-level quality (see
/code-quality-audit)
- For small projects (<5 files), a full architecture review may be overkill — suggest
/code-quality-audit instead
- Architectural recommendations should consider the team size and project phase
Related Skills
This skill applies the SOLID lens in report mode. For complementary lenses:
/deepening-review — Depth/seam paradigm in interactive mode. Surfaces shallow modules and grills the chosen one with the user. Uses the vocabulary in agent_docs/architecture-language.md. Run this skill for breadth, /deepening-review for surgical depth./interface-design — Once a deepening candidate is picked (or any new module is being designed), spawns parallel sub-agents producing competing interfaces, then compares./refactoring-guide — Sequences the actual changes once a direction is agreed.
