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. NOT for interactively finding shallow modules or designing one module's interface and seam, use module-deepening.
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.
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 responses before proceeding to Phase 2.
Phase 2: Dimension-by-Dimension Analysis
Evaluate the architecture across 7 weighted dimensions. For each dimension:
Read the relevant reference file for detailed sub-criteria and evaluation guidance
Evaluate each applicable sub-criterion against the input
Skip sub-criteria that are genuinely not applicable (document why)
For each finding, record: severity, description, evidence, impact, recommendation
Score the dimension on a 1-5 scale using references/scoring-rubric.md
Dimensions and References
#
Dimension
Weight
Reference File
1
Structural Integrity & Design Principles
20%
references/structural-integrity.md
2
Scalability
18%
references/scalability.md
3
Enterprise Readiness
15%
references/enterprise-readiness.md
4
Performance
17%
references/performance.md
5
Security
18%
references/security.md
6
Operational Excellence
7%
references/operational-excellence.md
7
Data Architecture
5%
references/data-architecture.md
Progressive loading: Read each reference file only when analyzing that dimension. Do not
load all references at once.
When analyzing Structural Integrity, also consult references/deep-module-analysis.md if
the review involves module boundaries, testability, service decomposition, or refactoring
recommendations.
Mode-specific guidance:
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
Level
Label
Meaning
S1
Critical
System will fail in production or has an active exploitable vulnerability
S2
High
Significant risk that will cause problems under realistic conditions
S3
Medium
Design weakness that limits growth or creates tech debt
S4
Low
Suboptimal choice with manageable impact
S5
Informational
Observation, best practice suggestion, or note for awareness
Architecture Pattern Evaluation
The review is architecture-pattern-agnostic. Do not assume any pattern is inherently superior.
Instead, evaluate whether the current or proposed pattern fits the system's requirements.
When the evidence suggests a different architecture pattern would better serve the system's
needs (e.g., a distributed monolith that should be either a true monolith or properly
decomposed microservices), include this as a finding with:
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
After completing all 7 dimensions, perform synthesis:
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.
Conflicting Decisions — Detect contradictions (e.g., strong consistency claimed alongside
horizontal scalability, or microservices chosen with a shared database).
Architectural Coherence — Do the parts fit together into a unified whole? Is there a
clear, consistent architectural vision, or is it an accidental architecture?
Requirements Alignment — Does this architecture actually solve the stated problem at
the stated scale? Is it over-engineered or under-engineered for the requirements?
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?
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
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
Score each dimension 1-5 using the rubric in references/scoring-rubric.md
Compute the weighted overall score:
Overall = Σ(dimension_score × weight) / 5 × 100
Assign a letter grade based on score range
Generate Report
Use assets/report-template.md as the skeleton. Fill in all sections:
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)
Before finalizing the report, verify ALL of the following. Non-compliance invalidates the review.
Scoring Format Compliance:
All dimension scores use 1-5 scale (not 1-10, not percentages)
Half-scores (e.g., 3.5) are permitted but must be justified
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
If any checkbox fails: Fix the issue before delivering the report. Do not proceed with a
non-compliant report.
Output the completed report as a markdown file.
Calibration Rules
Apply these rules to ensure fair, useful reviews:
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.
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.
"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.
Acknowledge strengths: Highlight what's done well. Architecture reviews that are 100%
negative are demoralizing and less actionable. Lead with genuine strengths.
Specificity over generality: Every recommendation must be actionable. "Add caching" is
insufficient. Specify what to cache, with what strategy, what TTL, and why.
Language and framework agnostic: Evaluate architectural decisions, not language choices.
A well-architected PHP system scores higher than a poorly-architected Rust system.
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
Rationalization
Reality
"It works in production already"
Working today doesn't mean it scales, maintains, or survives team turnover — architecture debt compounds silently
"We'll refactor when it becomes a problem"
By then the cost is 10x higher — refactoring under load with accumulated dependencies is surgical, not routine
"The framework handles that"
Frameworks provide defaults, not architecture — you're still responsible for boundaries, error propagation, and data flow
"It's an internal service, standards don't apply"
Internal services become external faster than you expect — technical debt migrates across boundaries
"Performance is fine for our current scale"
Architecture reviews evaluate the next 10x, not the current state — O(n^2) at 1k rows is invisible at 100k rows
"We don't have time for a full review"
Partial reviews create false confidence — better to review fewer dimensions thoroughly than all dimensions superficially
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
1---2name: architecture-reviewer3description: '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. NOT for interactively finding shallow modules or designing one module''s interface and seam, use module-deepening.'4metadata:5 source: https://skillmd.com/skills/mathews-tom/architecture-reviewer6 version: 1.1.27 category: review8 tags: [architecture, scalability, enterprise, security-audit]9 difficulty: advanced10 phase: review11---1213# Architecture Reviewer1415Systematic, framework-driven architecture review skill. Acts as a senior staff/principal16engineer performing a thorough architecture critique. Not a rubber-stamp — the skill is17opinionated, identifies real risks, and challenges assumptions. Every finding is tied to18a concrete impact and a concrete recommendation.1920## Workflow Overview2122The review proceeds in 4 phases:23241. **Input Classification & Context Gathering** — Determine review mode, scan inputs, ask25 clarifying questions (always).262. **Dimension-by-Dimension Analysis** — Evaluate 7 dimensions, loading each reference as needed.273. **Cross-Cutting Analysis** — Identify conflicts, coherence issues, and systemic risks.284. **Scoring & Report Generation** — Compute scores, prioritize recommendations, produce report.2930---3132## ⚠️ CRITICAL: Scoring & Format Quick Reference3334**These constraints are NON-NEGOTIABLE. Memorize before starting any review.**3536```text37SCORE SCALE: 1-5 only (NOT 1-10, NOT percentages)38 Half-scores (3.5) permitted with justification3940SEVERITY LABELS: [S1] Critical — System will fail or is exploitable41 [S2] High — Significant risk under realistic conditions42 [S3] Medium — Design weakness limiting growth43 [S4] Low — Suboptimal but manageable44 [S5] Info — Best practice suggestion (also used for strengths)4546DIMENSION WEIGHTS:47 Structural Integrity: 20% | Performance: 17%48 Scalability: 18% | Enterprise Readiness: 15%49 Security: 18% | Operational Excellence: 7%50 | Data Architecture: 5%5152GRADE BOUNDARIES:53 A = 90-100% | B = 80-89% | C = 70-79% | D = 60-69% | F = <60%5455FORMULA: Overall% = (Σ dimension_score × weight) / 5 × 10056```5758**Template compliance is mandatory.** See Phase 4 checklist before finalizing any report.5960---6162## Phase 1: Input Classification & Context Gathering6364### Step 0: Project Context Scan6566Before classifying the input, check for repo-local agent context when reviewing a codebase:6768- `docs/agents/domain.md` for `CONTEXT.md`, `CONTEXT-MAP.md`, and ADR lookup rules69- root or context-local `CONTEXT.md` files for domain vocabulary70- `docs/adr/` and context-local ADR directories for accepted architecture decisions7172Use glossary terms in findings and recommendations. Treat ADRs as constraints unless the73observed friction is severe enough to justify reopening the decision. If context files are74absent, continue with inferred vocabulary.7576### Step 1: Classify Input Mode7778Determine the review mode from what the user provides:7980- **Mode A — Codebase Review**: User provides a directory path, repository, or uploaded code files.81 - Run `scripts/scan_codebase.sh <path>` for structural overview.82 - Analysis is evidence-based: findings reference specific files, patterns, code locations.8384- **Mode B — Document Review**: User provides architecture documents, design specs, RFCs,85 diagrams, or verbal system descriptions. No codebase available.86 - Analysis is risk-based and completeness-focused.87 - Ask "what's NOT addressed?" as much as "what's wrong with what IS addressed?"8889- **Mode C — Hybrid**: User provides both code and documents.90 - Cross-reference documents against implementation.91 - Identify drift between intended and actual architecture.9293### Step 2: Initial Scan9495**If Mode A or C (codebase available):**96Run the scan script to get a structural fingerprint:9798```bash99bash scripts/scan_codebase.sh <codebase_path>100```101102Review the output to understand tech stack, service boundaries, infrastructure patterns,103and key configuration files before proceeding.104105**If Mode B or C (documents available):**106Read all provided documents. Extract:107108- Stated purpose, requirements, and constraints109- Component descriptions and boundaries110- Stated scale targets and SLAs111- Diagram contents and data flows112- Assumptions (explicit and implicit)113114### Step 3: Ask Clarifying Questions (ALWAYS)115116Always ask clarifying questions before starting the analysis. Tailor questions based on what117is already known from the input, but always cover these areas:118119**System Context:**120121- What is the system's primary purpose and who are its users?122- What is the current lifecycle stage? (greenfield design / early development / growth / mature production)123- What is the team size and structure? (solo dev, small team, multiple teams, org-wide)124125**Scale & Performance Expectations:**126127- What are the expected scale targets? (concurrent users, requests/sec, data volume, growth rate)128- Are there specific latency or throughput requirements?129130**Deployment & Operations:**131132- What is the target deployment environment? (cloud provider, on-prem, hybrid, multi-cloud)133- Is this consumer-facing, enterprise/B2B, internal tooling, or a combination?134135**Compliance & Security:**136137- Are there specific compliance requirements? (SOC2, HIPAA, GDPR, PCI-DSS, FedRAMP, other)138- Are there specific security requirements or threat model concerns?139140**Scope & Focus:**141142- Are there specific areas of concern the user wants prioritized?143- Are there known risks or trade-offs already accepted?144- Is there anything explicitly out of scope?145146Adapt the questions — skip what's already answered by the input, and add domain-specific147questions based on what you see. Keep questions focused and avoid overwhelming the user.148149Wait for the user's responses before proceeding to Phase 2.150151---152153## Phase 2: Dimension-by-Dimension Analysis154155Evaluate the architecture across 7 weighted dimensions. For each dimension:1561571. Read the relevant reference file for detailed sub-criteria and evaluation guidance1582. Evaluate each applicable sub-criterion against the input1593. Skip sub-criteria that are genuinely not applicable (document why)1604. For each finding, record: severity, description, evidence, impact, recommendation1615. Score the dimension on a 1-5 scale using `references/scoring-rubric.md`162163### Dimensions and References164165| # | Dimension | Weight | Reference File |166| --- | ---------------------------------------- | ------ | -------------------------------------- |167| 1 | Structural Integrity & Design Principles | 20% | `references/structural-integrity.md` |168| 2 | Scalability | 18% | `references/scalability.md` |169| 3 | Enterprise Readiness | 15% | `references/enterprise-readiness.md` |170| 4 | Performance | 17% | `references/performance.md` |171| 5 | Security | 18% | `references/security.md` |172| 6 | Operational Excellence | 7% | `references/operational-excellence.md` |173| 7 | Data Architecture | 5% | `references/data-architecture.md` |174175**Progressive loading:** Read each reference file only when analyzing that dimension. Do not176load all references at once.177178When analyzing Structural Integrity, also consult `references/deep-module-analysis.md` if179the review involves module boundaries, testability, service decomposition, or refactoring180recommendations.181182**Mode-specific guidance:**183184- For codebase analysis, also consult `references/codebase-signals.md` for what files and185 patterns to inspect per dimension.186- For document analysis, also consult `references/document-review-guide.md` for completeness187 checklists and common gaps.188189### Severity Levels for Findings190191| Level | Label | Meaning |192| ----- | ----------------- | ------------------------------------------------------------------------- |193| S1 | **Critical** | System will fail in production or has an active exploitable vulnerability |194| S2 | **High** | Significant risk that will cause problems under realistic conditions |195| S3 | **Medium** | Design weakness that limits growth or creates tech debt |196| S4 | **Low** | Suboptimal choice with manageable impact |197| S5 | **Informational** | Observation, best practice suggestion, or note for awareness |198199### Architecture Pattern Evaluation200201The review is architecture-pattern-agnostic. Do not assume any pattern is inherently superior.202Instead, evaluate whether the current or proposed pattern fits the system's requirements.203204When the evidence suggests a different architecture pattern would better serve the system's205needs (e.g., a distributed monolith that should be either a true monolith or properly206decomposed microservices), include this as a finding with:207208- What pattern is currently in use (or proposed)209- Why it's a poor fit for the requirements210- What alternative pattern would better serve the system and why211- Migration path considerations (effort, risk, phasing)212213---214215## Phase 3: Cross-Cutting Analysis216217After completing all 7 dimensions, perform synthesis:2182191. **Multi-Dimension Findings** — Identify issues that span dimensions (e.g., missing cache220 is both a performance AND scalability issue). Consolidate duplicates, note the cross-cutting221 nature.2222232. **Conflicting Decisions** — Detect contradictions (e.g., strong consistency claimed alongside224 horizontal scalability, or microservices chosen with a shared database).2252263. **Architectural Coherence** — Do the parts fit together into a unified whole? Is there a227 clear, consistent architectural vision, or is it an accidental architecture?2282294. **Requirements Alignment** — Does this architecture actually solve the stated problem at230 the stated scale? Is it over-engineered or under-engineered for the requirements?2312325. **Architecture Pattern Fitness** — Based on the full analysis, is the chosen (or emergent)233 architecture pattern the right one? If not, what would be better and why?2342356. **Severity Reconciliation** — Review findings that appear in multiple dimensions or combine236 to create compound risks. When cross-cutting analysis reveals that multiple issues together237 are more severe than individually assessed:238 - Escalate the severity of the systemic issue (e.g., three S3 findings that combine into239 an S1 systemic risk)240 - Document the escalation reasoning in the Cross-Cutting Concerns section241 - Ensure the final Systemic Risk section reflects the reconciled (higher) severity242 - Update recommendations priority to match the escalated severity2432447. **Systemic Risk** — Identify the single biggest risk. If one thing will sink this system,245 what is it? The systemic risk severity should reflect the reconciled assessment from step 6,246 which may be higher than any individual finding.247248---249250## Phase 4: Scoring & Report Generation251252### Compute Scores2532541. Score each dimension 1-5 using the rubric in `references/scoring-rubric.md`2552. Compute the weighted overall score:256 ```257 Overall = Σ(dimension_score × weight) / 5 × 100258 ```2593. Assign a letter grade based on score range260261### Generate Report262263Use `assets/report-template.md` as the skeleton. Fill in all sections:264265- Executive summary with overall score, top strengths, top risks266- Scorecard with per-dimension scores267- Detailed findings per dimension (sorted by severity within each)268- Cross-cutting concerns269- Prioritized recommendations in three tiers: Quick Wins, Medium-Term, Strategic270- Mermaid diagrams where they add clarity (dependency graphs, data flow issues, proposed271 improvements)272273### Template Compliance Checklist (MANDATORY)274275Before finalizing the report, verify ALL of the following. Non-compliance invalidates the review.276277**Scoring Format Compliance:**278279- [ ] All dimension scores use **1-5 scale** (not 1-10, not percentages)280- [ ] Half-scores (e.g., 3.5) are permitted but must be justified281- [ ] Weights are applied correctly: 20%, 18%, 18%, 17%, 15%, 7%, 5%282- [ ] Weighted contributions shown with 3 decimal precision (e.g., 0.700, not 0.7)283284**Severity Label Compliance:**285286- [ ] All findings use **[S1] through [S5]** severity labels287- [ ] S1 = Critical, S2 = High, S3 = Medium, S4 = Low, S5 = Informational288- [ ] Do NOT use: High/Medium/Low, P0-P3, Critical/Major/Minor, or numeric severity289- [ ] Severity matches criteria in SKILL.md severity table290291**Arithmetic Verification (from v1.1):**292293- [ ] Score Calculation Verification section is present in report294- [ ] Arithmetic breakdown shows each: score × weight = result295- [ ] Weighted sum is calculated and shown296- [ ] Percentage formula shown: weighted_sum / 5 × 100 = X%297- [ ] Grade matches percentage per rubric: A(90-100), B(80-89), C(70-79), D(60-69), F(<60)298- [ ] Verification checklist in report is completed299300**Report Structure Compliance:**301302- [ ] Meta table present (Review Date, Review Mode, System Stage, Overall Score)303- [ ] Executive Summary includes: Score, Visualization, Top 3 Strengths, Top 3 Risks, Verdict304- [ ] Scorecard table has all 7 dimensions with Score, Weight, Weighted, Key Finding columns305- [ ] Detailed Findings section has all 7 dimensions, each with dimension summary + findings306- [ ] Each finding has: Severity label, Evidence, Impact, Recommendation307- [ ] Cross-Cutting Concerns section present with: Multi-dimension issues, Conflicting decisions,308 Architectural coherence, Requirements alignment, Pattern fitness, Systemic risk309- [ ] Severity Reconciliation documented (if cross-cutting analysis escalated any severity)310- [ ] Recommendations section has three tiers: Quick Wins, Medium-Term, Strategic311- [ ] Appendix present with: Files reviewed, Assumptions, Out-of-scope, N/A sub-criteria, Methodology312313**Content Quality Gates:**314315- [ ] Every dimension has at least one strength (S5 positive finding) unless score is 1316- [ ] Every finding has specific evidence (file path, line number, or "not addressed in docs")317- [ ] Every recommendation is actionable (not "improve security" but specific steps)318- [ ] Systemic risk identified with blast radius assessment319320**If any checkbox fails:** Fix the issue before delivering the report. Do not proceed with a321non-compliant report.322323Output the completed report as a markdown file.324325---326327## Calibration Rules328329Apply these rules to ensure fair, useful reviews:3303311. **Stage-aware:** A greenfield design should not be penalized for missing implementation332 details. Evaluate plans, not missing code. Conversely, a mature production system should333 be held to a higher standard.3343352. **Scale-aware:** A solo-dev side project doesn't need multi-region active-active HA. Scale336 enterprise-readiness expectations to the stated requirements and team size.3373383. **"Not applicable" vs "Missing":** If the system is a batch analytics pipeline, P99 latency339 targets are irrelevant — mark as N/A, don't score as zero. If the system is a user-facing340 API and P99 latency is unaddressed, that's a finding.3413424. **Acknowledge strengths:** Highlight what's done well. Architecture reviews that are 100%343 negative are demoralizing and less actionable. Lead with genuine strengths.3443455. **Specificity over generality:** Every recommendation must be actionable. "Add caching" is346 insufficient. Specify what to cache, with what strategy, what TTL, and why.3473486. **Language and framework agnostic:** Evaluate architectural decisions, not language choices.349 A well-architected PHP system scores higher than a poorly-architected Rust system.3503517. **Honest about unknowns:** If the input doesn't provide enough information to evaluate a352 sub-criterion, say so explicitly. Don't guess. Flag it as requiring more information.353354## Rationalizations355356| Rationalization | Reality |357|---|---|358| "It works in production already" | Working today doesn't mean it scales, maintains, or survives team turnover — architecture debt compounds silently |359| "We'll refactor when it becomes a problem" | By then the cost is 10x higher — refactoring under load with accumulated dependencies is surgical, not routine |360| "The framework handles that" | Frameworks provide defaults, not architecture — you're still responsible for boundaries, error propagation, and data flow |361| "It's an internal service, standards don't apply" | Internal services become external faster than you expect — technical debt migrates across boundaries |362| "Performance is fine for our current scale" | Architecture reviews evaluate the next 10x, not the current state — O(n^2) at 1k rows is invisible at 100k rows |363| "We don't have time for a full review" | Partial reviews create false confidence — better to review fewer dimensions thoroughly than all dimensions superficially |364365## Red Flags366367- Evaluating only the happy path without tracing error propagation368- No scalability assessment (missing load projection, bottleneck identification)369- Scoring a dimension without reading the relevant code — relying on documentation alone370- Marking dimensions as N/A without justification371- Recommendations that are generic ("add caching", "use a queue") without specifying what, where, and why372- Reviewing implementation details instead of architectural decisions373374## Verification375376- [ ] All 7 dimensions evaluated with sub-criterion scores377- [ ] Each finding includes specific file/component references378- [ ] Scalability assessment includes concrete load projections or growth assumptions379- [ ] Cross-cutting analysis identifies at least one inter-dimension concern380- [ ] Every recommendation specifies what to change, where, and expected impact381- [ ] N/A dimensions justified explicitly — not silently skipped382- [ ] Final score is a weighted composite, not an average of vibes
Run npx get-skill add mathews-tom/architecture-reviewer in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
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. NOT for interactively finding shallow modules or designing one module's interface and seam, use module-deepening. It is listed under Security on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: executes scripts. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
mathews-tom (@mathews-tom) published this skill. Their other Agent Skills are listed on their SkillMD profile.