/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
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

Testing

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

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 Progress 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 invalidates the original reasoning | You're "cleaning up" a decision you don't fully understand |

**Output format:**

### Invariant Conflicts

[I1] **[Invariant name]** — [what decision it represents]
- **Location**: file.py:42
- **Anchor**: `verbatim source text at line 42`
- **Conflict**: [what change clashes]
- **Options**: Preserve / Layer / Revise
- **Recommendation**: ESCALATE TO HUMAN
- **Risk if wrong**: [what compounds]

**Why this matters:** Bad invariant decisions compound. After a few wrong calls the codebase becomes unsalvageable. This is a judgment problem rather than a context problem: the agent should surface it, not solve it.

Step 4: Principle Checks (`arch-review:principle-checks`)

**Load: `modules/principle-checks.md`**

• Law of Demeter.
• Anti-slop patterns.
• Security (input validation, least privilege).
• Performance (N+1 queries, caching).

Step 4.5: Ceremony Audit (`arch-review:ceremony-audit`)

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

Coupling analysi