/architecture-reviewer

name: architecture-reviewer
description: 'Architecture reviews across 7 dimensions (structural, scalability, enterprise readiness, performance, security, ops, data) with scored reports. Triggers on: "review architecture", "critique design", "audit system", "assess scalability", "enterprise readiness", "technical due diligence". NOT for diagrams, use architecture-diagram.'
metadata:
  version: 1.1.1
  category: review
  tags: [architecture, scalability, enterprise, security-audit]
  difficulty: advanced
  phase: review

Architecture Reviewer

Systematic, framework-driven architecture review skill. Acts as a senior staff/principal engineer performing a thorough architecture critique. Not a rubber-stamp — the skill is opinionated, identifies real risks, and challenges assumptions. Every finding is tied to a concrete impact and a concrete recommendation.

Workflow Overview

The review proceeds in 4 phases:

1. **Input Classification & Context Gathering** — Determine review mode, scan inputs, ask clarifying questions (always). 2. **Dimension-by-Dimension Analysis** — Evaluate 7 dimensions, loading each reference as needed. 3. **Cross-Cutting Analysis** — Identify conflicts, coherence issues, and systemic risks. 4. **Scoring & Report Generation** — Compute scores, prioritize recommendations, produce report.

---

⚠️ CRITICAL: Scoring & Format Quick Reference

**These constraints are NON-NEGOTIABLE. Memorize before starting any review.**

SCORE SCALE:     1-5 only (NOT 1-10, NOT percentages)
                 Half-scores (3.5) permitted with justification

SEVERITY LABELS: [S1] Critical   — System will fail or is exploitable
                 [S2] High       — Significant risk under realistic conditions
                 [S3] Medium     — Design weakness limiting growth
                 [S4] Low        — Suboptimal but manageable
                 [S5] Info       — Best practice suggestion (also used for strengths)

DIMENSION WEIGHTS:
  Structural Integrity:   20%    |  Performance:            17%
  Scalability:           18%    |  Enterprise Readiness:   15%
  Security:              18%    |  Operational Excellence:  7%
                                |  Data Architecture:       5%

GRADE BOUNDARIES:
  A = 90-100%  |  B = 80-89%  |  C = 70-79%  |  D = 60-69%  |  F = <60%

FORMULA:  Overall% = (Σ dimension_score × weight) / 5 × 100

**Template compliance is mandatory.** See Phase 4 checklist before finalizing any report.

---

Phase 1: Input Classification & Context Gathering

Step 0: Project Context Scan

Before classifying the input, check for repo-local agent context when reviewing a codebase:

• `docs/agents/domain.md` for `CONTEXT.md`, `CONTEXT-MAP.md`, and ADR lookup rules
• root or context-local `CONTEXT.md` files for domain vocabulary
• `docs/adr/` and context-local ADR directories for accepted architecture decisions

Use glossary terms in findings and recommendations. Treat ADRs as constraints unless the observed friction is severe enough to justify reopening the decision. If context files are absent, continue with inferred vocabulary.

Step 1: Classify Input Mode

Determine the review mode from what the user provides:

• **Mode A — Codebase Review**: User provides a directory path, repository, or uploaded code files.
• Run `scripts/scan_codebase.sh <path>` for structural overview.
• Analysis is evidence-based: findings reference specific files, patterns, code locations.

• **Mode B — Document Review**: User provides architecture documents, design specs, RFCs,

diagrams, or verbal system descriptions. No codebase available.

• Analysis is risk-based and completeness-focused.
• Ask "what's NOT addressed?" as much as "what's wrong with what IS addressed?"

• **Mode C — Hybrid**: User provides both code and documents.
• Cross-reference documents against implementation.
• Identify drift between intended and actual architecture.

Step 2: Initial Scan

**If Mode A or C (codebase available):** Run the scan script to get a structural fingerprint:

bash scripts/scan_codebase.sh <codebase_path>

Review the output to understand tech stack, service boundaries, infrastructure patterns, and key configuration files before proceeding.

**If Mode B or C (documents available):** Read all provided documents. Extract:

• Stated purpose, requirements, and constraints
• Component descriptions and boundaries
• Stated scale targets and SLAs
• Diagram contents and data flows
• Assumptions (explicit and implicit)

Step 3: Ask Clarifying Questions (ALWAYS)

Always ask clarifying questions before starting the analysis. Tailor questions based on what is already known from the input, but always cover these areas:

**System Context:**

• What is the system's primary purpose and who are its users?
• What is the current lifecycle stage? (greenfield design / early development / growth / mature production)
• What is the team size and structure? (solo dev, small team, multiple teams, org-wide)

**Scale & Performance Expectations:**

• What are the expected scale targets? (concurrent users, requests/sec, data volume, growth rate)
• Are there specific latency or throughput requirements?

**Deployment & Operations:**

• What is the target deployment environment? (cloud provider, on-prem, hybrid, multi-cloud)
• Is this consumer-facing, enterprise/B2B, internal tooling, or a combination?

**Compliance & Security:**

• Are there specific compliance requirements? (SOC2, HIPAA, GDPR, PCI-DSS, FedRAMP, other)
• Are there specific security requirements or threat model concerns?

**Scope & Focus:**

• Are there specific areas of concern the user wants prioritized?
• Are there known risks or trade-offs already accepted?
• Is there anything explicitly out of scope?

Adapt the questions — skip what's already answered by the input, and add domain-specific questions based on what you see. Keep questions focused and avoid overwhelming the user.

Wait for the user's resp