architecture-review

Architecture Review

When this skill is activated, perform a structured architecture review of a feature, module, or the full codebase and produce a docs/reviews/ARCHITECTURE_REVIEW.md report. This review evaluates the quality of the architecture as built — not the original intent.

Clarifying Questions

Before starting the review, ask the engineer the following questions. Skip any already clearly answered in the conversation. Wait for the answers before proceeding.

1. What is the scope — a specific module or feature, or the full codebase?
2. What is the goal of this review? (e.g. pre-release sanity check, before a major refactor, understanding current state, identifying technical debt)
3. Are there specific dimensions or concerns you want focused on — e.g. dependency direction, testability, layer separation?
4. Are there known problem areas you already suspect? Where does the code feel wrong to you?
5. Does a docs/DESIGN.md or docs/SYSTEM_DESIGN.md exist that the implementation should be compared against?

Steps

1. Use the answers above to set scope and focus; fall back to full codebase only if scope was not specified
2. Explore the directory and file structure to understand module boundaries
3. Read the key source files — focus on entry points, core domain logic, and infrastructure integrations
4. Evaluate the architecture against each dimension below
5. Identify violations with specific evidence (file path + line numbers)
6. Recommend concrete improvements, ordered by priority

Output

Write a file called docs/reviews/ARCHITECTURE_REVIEW.md (create the docs/reviews/ folder if it does not exist) with the following sections:

1. Scope & Summary

What was reviewed. One paragraph of overall verdict: is the architecture sound, concerning, or critical?

2. Architecture Map

A Mermaid diagram of the actual architecture as found in the code — layers, modules, and their dependencies:

graph TD
    subgraph Presentation
        A[HTTP Handler]
    end
    subgraph Domain
        B[OrderService]
        C[PriceCalculator]
    end
    subgraph Infrastructure
        D[PostgresRepository]
        E[StripeClient]
    end
    A --> B
    B --> C
    B --> D
    B --> E

3. Review Dimensions

Evaluate each dimension with a rating and findings:

3.1 Single Responsibility

Rating: Good | Fair | Poor

Are components doing one thing? List any components with mixed responsibilities.

3.2 Dependency Direction

Rating: Good | Fair | Poor

Does the dependency arrow point the right way? Domain must not depend on infrastructure. High-level policy must not depend on low-level detail. List every violation.

3.3 Layer Separation

Rating: Good | Fair | Poor

Are presentation, domain, and infrastructure concerns clearly separated? Are there layer leaks (e.g. SQL in a domain object, HTTP response objects in business logic)?

3.4 Interface Quality

Rating: Good | Fair | Poor

Are interfaces narrow and focused (Interface Segregation)? Are abstractions at the right level? Are there fat interfaces that force irrelevant implementations?

3.5 Coupling Quality

Rating: Good | Fair | Poor

A high-level pass only: is coupling conscious and managed, or are there accidental couplings that will cause change propagation? Give a rating and name the worst offenders — but do not produce a full coupling inventory here. For depth (dependency map, per-coupling classification, circular-dependency detection), run the dedicated coupling-review skill. If docs/reviews/COUPLING_REVIEW.md already exists, summarise and reference it instead of re-analysing.

3.6 Testability

Rating: Good | Fair | Poor

A high-level pass only: does the architecture allow components to be tested in isolation, and are there seams at significant boundaries? Give a rating and name the biggest blockers — but do not produce a full testability report here. For depth (per-component testability score, seam-by-seam fixes), run the dedicated testability-review skill. If docs/reviews/TESTABILITY_REVIEW.md already exists, summarise and reference it instead of re-analysing.

4. Findings

For each problem found across all dimensions:

Finding: {Short Title}

• Dimension: which of the 6 dimensions above
• Severity: Critical | Major | Minor
• Location: file path + line number(s)
• What's wrong: concrete description of the violation
• Recommended fix: the minimal change to resolve it — code snippet if helpful

5. Prioritized Improvements

Finding	Severity	Effort	Recommended Action
Domain imports Stripe SDK	Critical	Medium	Extract PaymentPort interface in domain layer

6. What's Working Well

Patterns or decisions in the codebase that are architecturally sound and should be preserved or extended. Good architecture reviews acknowledge what's right, not only what's wrong.

Rules

• Base all findings on actual code — never speculate or assume what the code "probably does"
• Always include file paths and line numbers; a finding without evidence is an opinion
• Severity reflects real-world impact: Critical = active risk to correctness or change cost; Major = significant friction; Minor = code smell
• Recommend the minimum change needed, not an ideal-world rewrite
• If a docs/DESIGN.md exists, compare the as-built architecture against the original design and note drift
• If docs/reviews/COUPLING_REVIEW.md or docs/reviews/TESTABILITY_REVIEW.md exist, reference them rather than duplicating their findings