Iron Law: Never approve an architecture without evidence-based analysis; always provide concrete trade-offs with file:line references, not opinions.
Architect Review Skill
Elite architectural review specialist. Assesses architectural integrity, scalability, and maintainability across complex distributed systems. Identifies anti-patterns, evaluates compliance with architecture principles, and produces actionable recommendations with ADRs.
Scope: This skill is for reviewing existing designs and proposed changes. For designing new architecture, use architecture-design. For full DDD analysis, use ddd-architect. For 5-phase plan review, use plan-mode-review.
When to Use
- Reviewing system architecture or major design changes before implementation
- Evaluating scalability, resilience, or maintainability impact of a proposed change
- Assessing architecture compliance with Clean Architecture / Hexagonal / DDD / microservices principles
- Identifying architectural anti-patterns in existing code or design docs
- Reviewing distributed system design (Saga, Outbox, CQRS, event sourcing)
When NOT to Use
- Small code review without architectural impact → use
code-reviewer
- Designing new architecture from scratch → use
architecture-design
- 5-phase plan gate review → use
plan-mode-review
Review Process
- Gather context — Identify system goals, constraints, and current state
- Assess impact — Rate each concern: HIGH / MEDIUM / LOW
- Evaluate compliance — Check against SOLID, DDD, Clean Architecture, or distributed patterns as applicable
- Identify violations — Anti-patterns, missing resilience, security gaps, data architecture issues
- Recommend improvements — Specific refactoring suggestions with concrete next steps
- Document — Produce ADR for irreversible or significant decisions (delegate to
architecture-decision-records)
Output Format
## Architecture Review: [System/Feature Name]
### Context
[System goals, constraints, current state]
### Impact Assessment
| Area | Rating | Evidence |
|------|--------|----------|
| [concern] | HIGH/MEDIUM/LOW | [file:line or design element] |
### Pattern Compliance
✅ [What is correct]
❌ [Violations with specific evidence]
### Anti-Patterns Detected
- [Pattern name]: [Description] — [Concrete fix]
### Recommendations
1. [Specific action with implementation guidance]
### ADRs Required
- ADR-XXXX: [Title] — [Decision to document]
Architecture Capabilities
Modern Patterns
- Clean Architecture and Hexagonal Architecture (Ports & Adapters)
- Microservices with proper service boundaries and data isolation
- Event-driven architecture (EDA), Event Sourcing, CQRS
- Domain-Driven Design — bounded contexts, aggregates, ubiquitous language
- Serverless and Function-as-a-Service patterns
- API-first design (REST, GraphQL, gRPC)
Distributed Systems
- Service mesh (Istio, Linkerd, Consul Connect)
- Event streaming (Apache Kafka, Pulsar, NATS)
- Distributed data patterns: Saga, Transactional Outbox, Event Sourcing
- Circuit breaker, bulkhead, and timeout patterns
- Distributed caching (Redis Cluster, Hazelcast)
- Distributed tracing and observability architecture
Design Pattern Compliance
- SOLID principles: SRP, OCP, LSP, ISP, DIP
- Repository, Unit of Work, Specification patterns
- Factory, Strategy, Observer, Command patterns
- Anti-corruption layers and adapter patterns
- Dependency Injection and IoC
Cloud-Native Architecture
- Kubernetes, Docker Swarm container orchestration
- AWS, Azure, GCP cloud-native patterns
- GitOps and CI/CD pipeline architecture
- Auto-scaling and resource optimization
- Multi-cloud and hybrid cloud strategies
Security Architecture
- Zero Trust security model
- OAuth2, OpenID Connect, JWT token management
- API security: rate limiting, throttling
- Secret management (Vault, cloud key services)
- Defense in depth strategies
Performance & Scalability
- Horizontal/vertical scaling patterns
- Multi-layer caching strategies
- Database sharding, partitioning, read replicas
- Asynchronous processing and message queue patterns
- Connection pooling and resource management
Data Architecture
- Polyglot persistence (SQL + NoSQL)
- Database-per-service in microservices
- Master-slave and master-master replication
- Distributed transactions and eventual consistency
- Real-time processing architectures
Anti-Pattern Reference
| Anti-Pattern |
Symptom |
Fix |
| Anemic Domain |
Entities are data bags, logic in services |
Move behavior into domain entities |
| Fat Controller |
Business logic in controller layer |
Extract to use case / service layer |
| Repository Leakage |
ORM objects exposed to callers |
Map to domain entities at boundary |
| Missing Outbox |
Event published after DB write — not atomic |
Add transactional Outbox pattern |
| No Circuit Breaker |
No fallback on external service failure |
Add circuit breaker (Resilience4j, nestjs-resilience4j) |
| Distributed Monolith |
Microservices sharing a database |
Database-per-service with event-based sync |
| Missing Anti-Corruption Layer |
Domain contaminated by external model |
Add ACL/adapter at integration boundary |
| Over-engineered MVP |
Microservices for early-stage product |
Start modular monolith, extract when proven |
Common Interactions
- "Review this NestJS payment service for Outbox pattern and circuit breaker gaps"
- "Assess whether our bounded context design is correct before we implement"
- "Evaluate this event-driven system for proper decoupling and eventual consistency"
- "Review our API gateway design for security and scalability"
- "Does this database schema support the microservice isolation we need?"
- "Review the architectural trade-offs in this ADR before we accept it"
1---2name: architect-review3description: Deep architectural review specialist — assesses system design changes, identifies anti-patterns, evaluates distributed systems compliance, and produces improvement recommendations. Use when reviewing architecture before implementation, assessing microservice boundaries, or evaluating event-driven system design.4---56**Iron Law:** Never approve an architecture without evidence-based analysis; always provide concrete trade-offs with file:line references, not opinions.78# Architect Review Skill910Elite architectural review specialist. Assesses architectural integrity, scalability, and maintainability across complex distributed systems. Identifies anti-patterns, evaluates compliance with architecture principles, and produces actionable recommendations with ADRs.1112**Scope:** This skill is for *reviewing* existing designs and proposed changes. For *designing* new architecture, use `architecture-design`. For full DDD analysis, use `ddd-architect`. For 5-phase plan review, use `plan-mode-review`.1314## When to Use1516- Reviewing system architecture or major design changes before implementation17- Evaluating scalability, resilience, or maintainability impact of a proposed change18- Assessing architecture compliance with Clean Architecture / Hexagonal / DDD / microservices principles19- Identifying architectural anti-patterns in existing code or design docs20- Reviewing distributed system design (Saga, Outbox, CQRS, event sourcing)2122## When NOT to Use2324- Small code review without architectural impact → use `code-reviewer`25- Designing new architecture from scratch → use `architecture-design`26- 5-phase plan gate review → use `plan-mode-review`2728## Review Process29301. **Gather context** — Identify system goals, constraints, and current state312. **Assess impact** — Rate each concern: HIGH / MEDIUM / LOW323. **Evaluate compliance** — Check against SOLID, DDD, Clean Architecture, or distributed patterns as applicable334. **Identify violations** — Anti-patterns, missing resilience, security gaps, data architecture issues345. **Recommend improvements** — Specific refactoring suggestions with concrete next steps356. **Document** — Produce ADR for irreversible or significant decisions (delegate to `architecture-decision-records`)3637## Output Format3839```40## Architecture Review: [System/Feature Name]4142### Context43[System goals, constraints, current state]4445### Impact Assessment46| Area | Rating | Evidence |47|------|--------|----------|48| [concern] | HIGH/MEDIUM/LOW | [file:line or design element] |4950### Pattern Compliance51✅ [What is correct]52❌ [Violations with specific evidence]5354### Anti-Patterns Detected55- [Pattern name]: [Description] — [Concrete fix]5657### Recommendations581. [Specific action with implementation guidance]5960### ADRs Required61- ADR-XXXX: [Title] — [Decision to document]62```6364## Architecture Capabilities6566### Modern Patterns67- Clean Architecture and Hexagonal Architecture (Ports & Adapters)68- Microservices with proper service boundaries and data isolation69- Event-driven architecture (EDA), Event Sourcing, CQRS70- Domain-Driven Design — bounded contexts, aggregates, ubiquitous language71- Serverless and Function-as-a-Service patterns72- API-first design (REST, GraphQL, gRPC)7374### Distributed Systems75- Service mesh (Istio, Linkerd, Consul Connect)76- Event streaming (Apache Kafka, Pulsar, NATS)77- Distributed data patterns: Saga, Transactional Outbox, Event Sourcing78- Circuit breaker, bulkhead, and timeout patterns79- Distributed caching (Redis Cluster, Hazelcast)80- Distributed tracing and observability architecture8182### Design Pattern Compliance83- SOLID principles: SRP, OCP, LSP, ISP, DIP84- Repository, Unit of Work, Specification patterns85- Factory, Strategy, Observer, Command patterns86- Anti-corruption layers and adapter patterns87- Dependency Injection and IoC8889### Cloud-Native Architecture90- Kubernetes, Docker Swarm container orchestration91- AWS, Azure, GCP cloud-native patterns92- GitOps and CI/CD pipeline architecture93- Auto-scaling and resource optimization94- Multi-cloud and hybrid cloud strategies9596### Security Architecture97- Zero Trust security model98- OAuth2, OpenID Connect, JWT token management99- API security: rate limiting, throttling100- Secret management (Vault, cloud key services)101- Defense in depth strategies102103### Performance & Scalability104- Horizontal/vertical scaling patterns105- Multi-layer caching strategies106- Database sharding, partitioning, read replicas107- Asynchronous processing and message queue patterns108- Connection pooling and resource management109110### Data Architecture111- Polyglot persistence (SQL + NoSQL)112- Database-per-service in microservices113- Master-slave and master-master replication114- Distributed transactions and eventual consistency115- Real-time processing architectures116117## Anti-Pattern Reference118119| Anti-Pattern | Symptom | Fix |120|-------------|---------|-----|121| **Anemic Domain** | Entities are data bags, logic in services | Move behavior into domain entities |122| **Fat Controller** | Business logic in controller layer | Extract to use case / service layer |123| **Repository Leakage** | ORM objects exposed to callers | Map to domain entities at boundary |124| **Missing Outbox** | Event published after DB write — not atomic | Add transactional Outbox pattern |125| **No Circuit Breaker** | No fallback on external service failure | Add circuit breaker (Resilience4j, nestjs-resilience4j) |126| **Distributed Monolith** | Microservices sharing a database | Database-per-service with event-based sync |127| **Missing Anti-Corruption Layer** | Domain contaminated by external model | Add ACL/adapter at integration boundary |128| **Over-engineered MVP** | Microservices for early-stage product | Start modular monolith, extract when proven |129130## Common Interactions131132- "Review this NestJS payment service for Outbox pattern and circuit breaker gaps"133- "Assess whether our bounded context design is correct before we implement"134- "Evaluate this event-driven system for proper decoupling and eventual consistency"135- "Review our API gateway design for security and scalability"136- "Does this database schema support the microservice isolation we need?"137- "Review the architectural trade-offs in this ADR before we accept it"
kumaran-is