Architecture Review

Review system architecture before major changes. This workflow validates design decisions against established patterns, checks ADR compliance, and identifies structural issues before they become expensive to fix.

When to Use This

• You are planning a major refactor and want to validate the approach.
• You need to assess whether the current architecture supports a new requirement.
• You want to check compliance with Architecture Decision Records (ADRs).
• A new team member needs to understand the system design.

What You'll Use

Walkthrough

Scenario: Review the architecture before a major refactor of the data access layer.

Step 1: Start the Review

Run /architecture-review and describe the scope:

"Review the data access layer architecture. We are considering moving from repository pattern to CQRS for better read/write separation."

Step 2: Architecture Assessment

The architecture-reviewer agent performs a principal-level assessment:

• Layering analysis — Are layers properly separated? Are there violations (e.g., controllers directly accessing the database)?
• Dependency direction — Do dependencies flow in the right direction? Are there circular dependencies?
• Pattern compliance — Does the current code follow the patterns declared in ADRs?
• API contract consistency — Are interfaces between layers consistent and well-defined?

Step 3: Review Findings

The review produces structured findings, each with:

• Location — Which files and components are affected
• Issue — What the architectural concern is
• Severity — How critical the issue is (info, warning, error)
• Recommendation — What to do about it

Step 4: Check Ontopix Patterns

If you are in an Ontopix project, also query the MCP server for relevant patterns:

"Search ontopix docs for data access patterns"

This ensures your architecture aligns with team conventions, not just general best practices.

Quick Reference

Tips

• Run architecture reviews before starting implementation, not after. Fixing architecture post-implementation is much more expensive.
• The architecture-reviewer agent checks ADRs automatically if they exist in your project. Keep ADRs up to date for the best results.
• For Ontopix projects, always cross-reference findings with patterns from docs.ontopix.dev. The ontopix plugin's MCP integration makes this easy.
• Combine with imbue's /structured-review for evidence-based architectural decisions.

See Also

• pensive plugin — Full plugin documentation
• Specification workflow — Define requirements before reviewing architecture
• Planning workflow — Plan implementation after architecture is validated