Architecture Review

Conducts comprehensive multi-perspective architecture reviews with all team members.

Process Overview

Determine Scope - Identify what to review (version, feature, or component)
Load Team - Read members from .architecture/members.yml and check pragmatic mode
Analyze System - Examine architecture using Read, Glob, Grep, and git tools
Individual Reviews - Each member reviews from their specialized perspective
Collaborative Discussion - Synthesize findings and establish priorities
Create Document - Generate comprehensive review using template
Report Results - Summarize findings and next steps for user

Detailed guidance: references/review-process.md

Workflow Steps

1. Determine Scope

Identify review target and create filename:

Version: "version X.Y.Z" → X-Y-Z.md
Feature: "feature name" → feature-kebab-case.md
Component: "component name" → component-kebab-case.md

Apply input validation (see _patterns.md § Filename Sanitization).

2. Load Configuration and Team

cat .architecture/config.yml     # Check pragmatic_mode.enabled
cat .architecture/members.yml    # Load all members

Include Pragmatic Enforcer if pragmatic mode enabled for reviews.

3. Analyze the Target

Use available tools to examine the system:

Read - Code, configs, documentation
Glob - Find files by pattern
Grep - Search for specific patterns
Bash(git:*) - Git history and status

Focus based on review type:

Version: Overall architecture, components, patterns, technical debt
Feature: Implementation, integration, security, performance
Component: Structure, dependencies, boundaries, interfaces

4. Conduct Individual Member Reviews

For each member in members.yml, write a review including:

Perspective statement
Key observations (3-5)
Strengths (3-5)
Concerns with impact and recommendations (3-7)
Prioritized recommendations with effort estimates (3-7)

Format details: references/review-process.md § Individual Member Review Format

Pragmatic integration: If enabled, add pragmatic analysis after each member. See references/pragmatic-integration.md

5. Facilitate Collaborative Discussion

Synthesize findings:

Identify common concerns
Discuss disagreements
Establish consensus
Prioritize: Critical (0-2 weeks) | Important (2-8 weeks) | Nice-to-Have (2-6 months)

Discussion format: references/review-process.md § Collaborative Discussion

6. Create Review Document

Load template and fill in all sections:

cat .claude/skills/architecture-review/assets/review-template.md

Include:

Executive summary and overall assessment
Individual member reviews
Collaborative discussion
Consolidated findings (strengths, improvements, debt, risks)
Recommendations (immediate, short-term, long-term)
Success metrics and follow-up plan

Save to .architecture/reviews/[filename].md

Template: assets/review-template.md

7. Report to User

Architecture Review Complete: [Target]

Location: .architecture/reviews/[filename].md
Overall Assessment: [Strong | Adequate | Needs Improvement]

Top 3 Priorities:
1. [Priority 1]
2. [Priority 2]
3. [Priority 3]

Immediate Actions:
- [Action 1]
- [Action 2]

Next Steps:
- Review with team
- "Start architecture recalibration for [target]"
- Create ADRs for key decisions

Related Skills

Before: architecture-status, list-members During: specialist-review, create-adr After: architecture-recalibration, create-adr

Documentation

Process guide: references/review-process.md
Pragmatic mode: references/pragmatic-integration.md
Template: assets/review-template.md
Patterns: ../_patterns.md