Architecture Reviewer

Workflow Overview

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

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

Phase 1: Input Classification & Context Gathering

Step 1: Classify Input Mode

• 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

bash scripts/scan_codebase.sh <codebase_path>

• 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)

• 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)

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

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

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

• 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?

Phase 2: Dimension-by-Dimension Analysis

1. Read the relevant reference file for detailed sub-criteria and evaluation guidance
2. Evaluate each applicable sub-criterion against the input
3. Skip sub-criteria that are genuinely not applicable (document why)
4. For each finding, record: severity, description, evidence, impact, recommendation
5. Score the dimension on a 1-5 scale using

   references/scoring-rubric.md

Dimensions and References

references/structural-integrity.md

references/scalability.md

references/enterprise-readiness.md

references/performance.md

references/security.md

references/operational-excellence.md

references/data-architecture.md

• For codebase analysis, also consult

  references/codebase-signals.md

  for what files and patterns to inspect per dimension.
• For document analysis, also consult

  references/document-review-guide.md

  for completeness checklists and common gaps.

Severity Levels for Findings

Architecture Pattern Evaluation

• What pattern is currently in use (or proposed)
• Why it's a poor fit for the requirements
• What alternative pattern would better serve the system and why
• Migration path considerations (effort, risk, phasing)

Phase 3: Cross-Cutting Analysis

1. Multi-Dimension Findings — Identify issues that span dimensions (e.g., missing cache is both a performance AND scalability issue). Consolidate duplicates, note the cross-cutting nature.
2. Conflicting Decisions — Detect contradictions (e.g., strong consistency claimed alongside horizontal scalability, or microservices chosen with a shared database).
3. Architectural Coherence — Do the parts fit together into a unified whole? Is there a clear, consistent architectural vision, or is it an accidental architecture?
4. Requirements Alignment — Does this architecture actually solve the stated problem at the stated scale? Is it over-engineered or under-engineered for the requirements?
5. Architecture Pattern Fitness — Based on the full analysis, is the chosen (or emergent) architecture pattern the right one? If not, what would be better and why?
6. Severity Reconciliation — Review findings that appear in multiple dimensions or combine to create compound risks. When cross-cutting analysis reveals that multiple issues together are more severe than individually assessed:
   • Escalate the severity of the systemic issue (e.g., three S3 findings that combine into an S1 systemic risk)
   • Document the escalation reasoning in the Cross-Cutting Concerns section
   • Ensure the final Systemic Risk section reflects the reconciled (higher) severity
   • Update recommendations priority to match the escalated severity
7. Systemic Risk — Identify the single biggest risk. If one thing will sink this system, what is it? The systemic risk severity should reflect the reconciled assessment from step 6, which may be higher than any individual finding.

Phase 4: Scoring & Report Generation

Compute Scores

1. Score each dimension 1-5 using the rubric in

   references/scoring-rubric.md

2. Compute the weighted overall score:

   Overall = Σ(dimension_score × weight) / 5 × 100

3. Assign a letter grade based on score range

Generate Report

assets/report-template.md

• Executive summary with overall score, top strengths, top risks
• Scorecard with per-dimension scores
• Detailed findings per dimension (sorted by severity within each)
• Cross-cutting concerns
• Prioritized recommendations in three tiers: Quick Wins, Medium-Term, Strategic
• Mermaid diagrams where they add clarity (dependency graphs, data flow issues, proposed improvements)

Template Compliance Checklist (MANDATORY)

• All dimension scores use 1-5 scale (not 1-10, not percentages)
• Half-scores (e.g., 3.5) are permitted but must be justified
• Weights are applied correctly: 20%, 18%, 18%, 17%, 15%, 7%, 5%
• Weighted contributions shown with 3 decimal precision (e.g., 0.700, not 0.7)

• All findings use [S1] through [S5] severity labels
• S1 = Critical, S2 = High, S3 = Medium, S4 = Low, S5 = Informational
• Do NOT use: High/Medium/Low, P0-P3, Critical/Major/Minor, or numeric severity
• Severity matches criteria in SKILL.md severity table

• Score Calculation Verification section is present in report
• Arithmetic breakdown shows each: score × weight = result
• Weighted sum is calculated and shown
• Percentage formula shown: weighted_sum / 5 × 100 = X%
• Grade matches percentage per rubric: A(90-100), B(80-89), C(70-79), D(60-69), F(<60)
• Verification checklist in report is completed

• Meta table present (Review Date, Review Mode, System Stage, Overall Score)
• Executive Summary includes: Score, Visualization, Top 3 Strengths, Top 3 Risks, Verdict
• Scorecard table has all 7 dimensions with Score, Weight, Weighted, Key Finding columns
• Detailed Findings section has all 7 dimensions, each with dimension summary + findings
• Each finding has: Severity label, Evidence, Impact, Recommendation
• Cross-Cutting Concerns section present with: Multi-dimension issues, Conflicting decisions, Architectural coherence, Requirements alignment, Pattern fitness, Systemic risk
• Severity Reconciliation documented (if cross-cutting analysis escalated any severity)
• Recommendations section has three tiers: Quick Wins, Medium-Term, Strategic
• Appendix present with: Files reviewed, Assumptions, Out-of-scope, N/A sub-criteria, Methodology

• Every dimension has at least one strength (S5 positive finding) unless score is 1
• Every finding has specific evidence (file path, line number, or "not addressed in docs")
• Every recommendation is actionable (not "improve security" but specific steps)
• Systemic risk identified with blast radius assessment

Calibration Rules

1. Stage-aware: A greenfield design should not be penalized for missing implementation details. Evaluate plans, not missing code. Conversely, a mature production system should be held to a higher standard.
2. Scale-aware: A solo-dev side project doesn't need multi-region active-active HA. Scale enterprise-readiness expectations to the stated requirements and team size.
3. "Not applicable" vs "Missing": If the system is a batch analytics pipeline, P99 latency targets are irrelevant — mark as N/A, don't score as zero. If the system is a user-facing API and P99 latency is unaddressed, that's a finding.
4. Acknowledge strengths: Highlight what's done well. Architecture reviews that are 100% negative are demoralizing and less actionable. Lead with genuine strengths.
5. Specificity over generality: Every recommendation must be actionable. "Add caching" is insufficient. Specify what to cache, with what strategy, what TTL, and why.
6. Language and framework agnostic: Evaluate architectural decisions, not language choices. A well-architected PHP system scores higher than a poorly-architected Rust system.
7. Honest about unknowns: If the input doesn't provide enough information to evaluate a sub-criterion, say so explicitly. Don't guess. Flag it as requiring more information.

Rationalizations

Red Flags

• Evaluating only the happy path without tracing error propagation
• No scalability assessment (missing load projection, bottleneck identification)
• Scoring a dimension without reading the relevant code — relying on documentation alone
• Marking dimensions as N/A without justification
• Recommendations that are generic ("add caching", "use a queue") without specifying what, where, and why
• Reviewing implementation details instead of architectural decisions

Verification

• All 7 dimensions evaluated with sub-criterion scores
• Each finding includes specific file/component references
• Scalability assessment includes concrete load projections or growth assumptions
• Cross-cutting analysis identifies at least one inter-dimension concern
• Every recommendation specifies what to change, where, and expected impact
• N/A dimensions justified explicitly — not silently skipped
• Final score is a weighted composite, not an average of vibes