/architecture-review

name: architecture-review
description: Assesses architecture decisions, ADR compliance, and coupling. Use when evaluating design changes or validating structural decisions before merging.
alwaysApply: false
category: architecture
tags:
- architecture
- design
- adr
- coupling
- patterns
- principles
tools: []
usage_patterns:
- architecture-assessment
- adr-audit
- refactor-review
- design-validation
complexity: advanced
model_hint: deep
estimated_tokens: 300
progressive_loading: true
dependencies:
- imbue:proof-of-work
- imbue:diff-analysis/modules/risk-assessment-framework
- imbue:review-core
- imbue:structured-output
modules:
- modules/adr-audit.md
- modules/coupling-analysis.md
- modules/principle-checks.md
- modules/fpf-methodology.md
- modules/ceremony-audit.md

Table of Contents

• [Quick Start](#quick-start)
• [When to Use](#when-to-use)
• [Progressive Loading](#progressive-loading)
• [Required TodoWrite Items](#required-todowrite-items)
• [Workflow](#workflow)
• [Step 1: Establish Context (`arch-review:context-established`)](#step-1:-establish-context-(arch-review:context-established))
• [Step 2: ADR Audit (`arch-review:adr-audit`)](#step-2:-adr-audit-(arch-review:adr-audit))
• [Step 3: Interaction Mapping (`arch-review:interaction-mapping`)](#step-3:-interaction-mapping-(arch-review:interaction-mapping))
• [Step 4: Principle Checks (`arch-review:principle-checks`)](#step-4:-principle-checks-(arch-review:principle-checks))
• [Step 5: Risks and Actions (`arch-review:risks-actions`)](#step-5:-risks-and-actions-(arch-review:risks-actions))
• [Testing](#testing)

Testing

Run `pytest plugins/pensive/tests/skills/test_architecture_review.py` to verify review logic.

• [Architecture Principles Checklist](#architecture-principles-checklist)
• [Coupling](#coupling)
• [Cohesion](#cohesion)
• [Layering](#layering)
• [Evolution](#evolution)

Architecture Review Workflow

Architecture assessment against ADRs and design principles.

Quick Start

/architecture-review

When To Use

• Approving reimplementations.
• Large-scale refactoring reviews.
• System design changes.
• New module/service introduction.
• Dependency restructuring.

When NOT To Use

• Selecting architecture paradigms - use archetypes

skills

• API surface review - use api-review
• Selecting architecture paradigms - use archetypes

skills

• API surface review - use api-review

Progressive Loading

Load modules based on review scope:

• **`modules/adr-audit.md`** (~400 tokens): ADR verification and documentation.
• **`modules/coupling-analysis.md`** (~450 tokens): Dependency analysis and boundary violations.
• **`modules/principle-checks.md`** (~500 tokens): Code quality, security, and performance.
• **`modules/fpf-methodology.md`** (~800 tokens): FPF (Functional, Practical, Foundation) multi-perspective review methodology.
• **`modules/ceremony-audit.md`** (~600 tokens): Manual lenses for mapping layers that never diverge. Passthrough mappers, twin types, speculative DTOs, single-implementation interfaces. Includes the IO boundary counter-signal.

Load all modules for full reviews. For focused reviews, load only relevant modules.

Required TodoWrite Items

1. `arch-review:context-established`: Repository, branch, motivation. 2. `arch-review:adr-audit`: ADR verification and new ADR needs. 3. `arch-review:interaction-mapping`: Module coupling analysis. 4. `arch-review:invariant-check`: Invariant conflict detection and 3-option analysis. 5. `arch-review:principle-checks`: LoD, security, performance. 6. `arch-review:ceremony-audit`: Mapping layers that never diverge. 7. `arch-review:risks-actions`: Recommendation and follow-ups. 8. `arch-review:findings-verified`

Workflow

Step 1: Establish Context (`arch-review:context-established`)

Confirm repository and branch:

pwd
git status -sb

Document:

• Feature/bug/epic motivating review.
• Affected subsystems.
• Architectural intent from README/docs.
• Design trade-off assumptions.

Step 2: ADR Audit (`arch-review:adr-audit`)

**Load: `modules/adr-audit.md`**

• Locate ADRs in project.
• Verify required sections.
• Check status flow.
• Confirm immutability compliance.
• Flag need for new ADRs.

Step 3: Interaction Mapping (`arch-review:interaction-mapping`)

**Load: `modules/coupling-analysis.md`**

• Diagram before/after module interactions.
• Verify composition boundaries.
• Check data ownership clarity.
• Validate dependency flow direction.
• Identify coupling violations.

Step 3.5: Invariant Conflict Detection (`arch-review:invariant-check`)

Before checking principles, identify whether the changes conflict with existing design invariants. This is the highest-judgment step in architecture review: models get this wrong more often than any other call.

**Identify existing invariants:**

1. Scan ADRs for recorded decisions still in "accepted" status 2. Check module boundaries (are imports crossing layers that previously didn't?) 3. Check data flow direction (does data now flow in a new direction?) 4. Check API contracts (are public interfaces changing shape?) 5. Check structural patterns (is a new pattern being introduced alongside an existing one?)

# Detect boundary crossings in changed files
git diff --name-only | while read f; do
  head -20 "$f" 2>/dev/null | rg "^(import|from|use |require)" || true
done

**When a conflict is detected:**

Do NOT recommend a resolution. Present the three options and escalate to human judgment:

| Option | When Right | When Wrong | |--------|------------|------------| | **Preserve invariant** (reject feature) | Invariant simplifies many things; feature is marginal | Feature is genuinely needed and invariant is stale | | **Layer on top** (add inelegantly) | Feature is needed; invariant still valuable; imperfection is OK | Layering creates a maintenance trap that will compound | | **Revise invariant** (change the design) | Genuine new learning invalida