Architecture Review

---
name: architecture-review
description: Scan codebase for shallow modules. Present deep refactoring targets in a visual HTML report. YAGNI-first.
disable-model-invocation: true
---

# Architecture Review

Surface architectural friction. Propose **deepening opportunities** (converting shallow modules into deep ones). Optimize for testability and locality.

**Strict Vocabulary Definition:** 
Always use: **module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**. 
Never use: component, service, API, boundary. Use `CONTEXT.md` for domain terminology. Respect existing `docs/adr/`.

## Process

### 1. Explore (YAGNI)

Do not review stable code. Deepening only pays off if the code changes. 

- **Target Hotspots:** Run `git log --oneline` to locate frequently touched files.
- **Read Context:** Parse `CONTEXT.md` and `docs/adr/` for the target area.
- **Audit for Friction (Spawn Sub-Agent):**
  - Locate **shallow modules** (interface complexity ≈ implementation complexity).
  - Locate leaked abstractions (e.g., Eloquent queries bleeding into Vue components).
  - Identify pure functions lacking **locality** (extracted for tests, but real bugs hide in the untested callers).
- **The Deletion Test:** Would deleting this module concentrate complexity, or just move it? If it concentrates, it is shallow. Target it.

### 2. Generate HTML Report

Write a self-contained HTML file to the OS temp directory. Do not pollute the repo.

- **Path:** `/tmp/architecture-review-<timestamp>.html` (Fallback: `$TMPDIR`).
- **Open:** Execute `xdg-open <path>`.
- **Format:** Refer to `HTML-REPORT.md` for the strict Tailwind/Mermaid visual spec.
- **Candidate Data:** Files, Problem, Solution, Benefits (using strict vocabulary), Recommendation Strength (`Strong`, `Worth exploring`, `Speculative`), Before/After Diagram.
- **ADR Conflicts:** Only surface a conflicting candidate if the friction justifies reopening the ADR. Mark it explicitly.

*Do not propose new interfaces yet. Output the file, open it, and ask: "Which of these do we explore?"*

### 3. The Grilling Loop

Once the user selects a candidate, execute `grill` to stress-test the architectural decision tree.

**Inline Side Effects:**
- **Missing Domain Term?** Update `CONTEXT.md` immediately.
- **User Rejects Candidate?** Ask to record an ADR to prevent future re-suggestions. (Skip if the reason is ephemeral).
- **Alternative Interfaces?** Spawn parallel sub-agents to design it twice using the codebase-design principles.