rai-architecture-review

What problem does it solve?

Prevents over-engineering and unnecessary complexity by judging whether implemented code is necessary and proportional to the design intent, helping teams avoid gold-plating and speculative work.

Core Features & Use Cases

• Necessity Audit (YAGNI): Detect single implementations, wrappers without logic, unused parameters, test-only consumers, and dead exports.
• Proportionality & Duplication Checks: Measure indirection depth, abstraction-to-LOC ratio, configuration misuse, semantic duplication, pattern drift, and import fan-in.
• Systemic & Lean Compliance (epic scope): Identify orphaned abstractions, coupling direction issues, cyclic dependencies, shotgun surgery, and violations of MVP/design/patterns.
• Use Cases: Run after a story implementation to verify minimal, correct design; run at epic close for cross-module systemic issues; run on-demand when complexity feels disproportionate.

Quick Start

Run an architecture review on the current story by loading the design document, changed files, and relevant patterns, then produce heuristic-tagged findings and a verdict.