Arch Review

arch-review

Review implementation against Arc42 architecture documentation

When to Use

Use this skill when:

• Completing a significant feature
• Before merging architectural changes
• Reviewing code for architecture compliance
• Validating design decisions against documented architecture

Invocation

/arch-review [scope]

Scope options:

• feature - Review current feature branch (default)
• pr - Review specific PR
• commit - Review specific commit range
• full - Full codebase architecture review

Prerequisites

• Arc42 documentation must exist in docs/architecture/
• For feature review: must be on a feature branch
• Git history available for change analysis

Workflow

Phase 1: Load Architecture Context

Read Arc42 documentation sections:

• 01-intro-goals.md - System goals and constraints
• 04-solution-strategy.md - Key architectural decisions
• 05-building-blocks.md - Component structure
• 06-runtime.md - Runtime behavior
• 08-concepts.md - Cross-cutting concerns
• 09-decisions.md - Architecture decisions (ADRs)

Phase 2: Analyze Changes

For feature/PR/commit scope:

# Get changed files
git diff main..HEAD --name-only

# Get change summary
git diff main..HEAD --stat

Categorize changes:

• New components: Files in new directories
• Modified components: Changes to existing modules
• Cross-cutting: Changes affecting multiple areas
• Configuration: Config/setup changes

Phase 3: Architecture Compliance Check

For each changed component, verify against Arc42:

Building Block View (§5)

• Does component exist in documented structure?
• Are dependencies as documented?
• Are responsibilities aligned?

Runtime View (§6)

• Do flows match documented sequences?
• Are interfaces as specified?
• Are error paths handled?

Cross-cutting Concepts (§8)

• Error handling consistent?
• Logging follows patterns?
• Security considerations met?

Architecture Decisions (§9)

• ADRs followed?
• New decisions documented?
• Superseded decisions updated?

Phase 4: Identify Violations

Categorize findings:

VIOLATION - Direct contradiction of documented architecture

• Component in wrong layer
• Forbidden dependency
• Bypassing required interface

DRIFT - Gradual deviation from architecture

• Undocumented component
• Implicit dependency
• Missing abstraction

ENHANCEMENT - Valid extension needing documentation

• New component following patterns
• New capability within bounds
• Performance optimization

Phase 5: Generate Report

# Architecture Review Report

> Feature: EP01 - Core Foundation
> Branch: ep01-core-foundation
> Reviewed: 2026-01-15

## Summary

| Category | Count | Status |
|----------|-------|--------|
| Violations | 0 | ✓ |
| Drift | 2 | ⚠️ |
| Enhancements | 3 | ℹ️ |

**Overall**: PASS (documentation updates needed)

## Changes Analyzed

| File | Category | Arc42 Section |
|------|----------|---------------|
| src/core/analyzer.ts | New | §5.1 Core |
| src/rules/index.ts | Modified | §5.2 Rules |
| src/utils/logger.ts | New | §8.3 Logging |

## Findings

### Drift

**D1: Undocumented utility module**
- Location: `src/utils/logger.ts`
- Issue: New logging utility not in building blocks
- Impact: Low - follows patterns
- Recommendation: Add to §5.3 Utilities

**D2: Implicit dependency**
- Location: `src/rules/index.ts` → `src/utils/`
- Issue: Rules depending on utils not documented
- Impact: Low - reasonable dependency
- Recommendation: Update §5.2 dependency diagram

### Enhancements

**E1: New analyzer component**
- Location: `src/core/analyzer.ts`
- Alignment: Follows §5.1 Core structure
- Recommendation: Document in §5.1.2 Analyzers

[...]

## Recommendations

1. **Required**: Update §5.3 with utils/logger.ts
2. **Required**: Update §5.2 dependency diagram
3. **Suggested**: Add §5.1.2 for analyzer components
4. **Optional**: Consider ADR for logging approach

## Architecture Debt

| Item | Severity | Effort |
|------|----------|--------|
| Utils documentation | Low | 30 min |
| Dependency diagram | Low | 15 min |

Constitution Alignment Mapping

Map constitution principles to Arc42 sections:

Output

On completion:

Architecture review complete!

  Feature:    EP01 - Core Foundation
  Status:     PASS (updates needed)

  Findings:
    Violations:    0
    Drift:         2
    Enhancements:  3

  Arc42 Updates Needed:
    - §5.3 Utilities (add logger)
    - §5.2 Rules (update diagram)
    - §5.1 Core (document analyzer)

  Report: specs/ep01-core-foundation/arch-review.md

Merge approved. Update Arc42 docs in follow-up PR.

Integration with Arc42

This skill reads from these Arc42 sections:

Handoff

After review, suggest:

• Update Arc42 docs for drift items
• Create ADRs for new decisions
• /dev.integration-check for final validation