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