Table of Contents

• Quick Start
• When to Use
• Progressive Loading
• Required TodoWrite Items
• Workflow
• Step 1: Establish Context (

  arch-review:context-established

  )
• Step 2: ADR Audit (

  arch-review:adr-audit

  )
• Step 3: Interaction Mapping (

  arch-review:interaction-mapping

  )
• Step 4: Principle Checks (

  arch-review:principle-checks

  )
• Step 5: Risks and Actions (

  arch-review:risks-actions

  )
• Testing

Testing

Run

pytest plugins/pensive/tests/skills/test_architecture_review.py

to verify review logic.

• Architecture Principles Checklist
• Coupling
• Cohesion
• Layering
• 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.

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:principle-checks

   : LoD, security, performance.

5. arch-review:risks-actions

   : Recommendation and follow-ups.

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 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 5: Risks and Actions (

arch-review:risks-actions

)

Summarize using

imbue:diff-analysis/modules/risk-assessment-framework

:

• Current vs proposed architecture.
• Business impact.
• Technical debt implications.

List follow-ups with owners and dates.

Provide recommendation:

• Approve: Architecture sound.
• Approve with actions: Minor issues to address.
• Block: Fundamental problems requiring redesign.

Architecture Principles Checklist

Coupling

• Dependencies follow defined boundaries.
• No circular dependencies.
• Extension points used properly.
• Abstractions don't leak.

Cohesion

• Related functionality grouped.
• Single responsibility per module.
• Clear module purposes.

Layering

• Layers have clear responsibilities.
• Dependencies flow downward.
• No layer bypassing.

Evolution

• Changes are reversible.
• Migration paths are clear.
• ADRs document decisions.