Codebase Architecture Reviewer

---
name: codebase-architecture-reviewer
description: Use when improving architecture or finding refactoring opportunities — consolidating tightly-coupled modules, making a codebase more testable. Triggers on "improve architecture", "refactoring opportunities", "shallow modules", "make this more testable", "architecture review".
---

# Codebase Architecture Reviewer

Surface architectural friction and propose **deepening** refactors — turning shallow modules into deep ones. A deep module hides a lot of behavior behind a small interface; a shallow one has an interface nearly as complex as its implementation, so it earns nothing. Aim: testability and navigability.

## Use the vocabulary precisely

Consistent language is the point — don't drift into vague words like "component," "service," or "boundary."

- **Module** — anything with an interface and an implementation (function, class, package).
- **Interface** — everything a caller must know to use it: types, invariants, error modes, ordering, config. Not just the signature.
- **Depth** — leverage at the interface: lots of behavior behind a small surface. Deep = high leverage; shallow = low.
- **Seam** — where an interface lives; a place behavior can change without editing in place. One adapter is a *hypothetical* seam; two adapters make it a *real* one.

## The deletion test

For anything you suspect is shallow: imagine deleting it. If complexity simply vanishes, it was a pass-through adding indirection for nothing. If complexity reappears, duplicated across its callers, it was earning its keep. "Concentrates complexity when deleted" is the signal of a module worth having.

## Process

1. **Explore for friction** — read the area, including any domain glossary and architecture decisions already recorded. Note where understanding one concept means hopping across many tiny modules; where interfaces are as complex as implementations; where functions were extracted only for testability but the real bugs live in how they're called.
2. **Present candidates** — for each: the files involved, the friction, a plain-English deepening, the benefit in terms of leverage and locality, and a before/after sketch. Tag each with a recommendation strength (strong / worth exploring / speculative).
3. **Stop before redesigning.** Don't propose detailed new interfaces yet — present the candidates and let the user pick which to pursue.

## Respect existing decisions

If a candidate contradicts a recorded architecture decision (an ADR), only raise it when the friction is real enough to justify reopening that decision — and mark it clearly. Don't re-litigate settled calls.

## Anti-patterns

- Drifting from the precise vocabulary into mushy "boundaries" and "services"
- Proposing a rewrite instead of ranked, testable candidates
- Extracting pure functions for testability while the real coupling stays put
- Designing the new interfaces before the user has chosen what to tackle