Architecture Review — Find Deepening Opportunities

Surface architectural friction and propose refactors that turn shallow modules into deep ones. A deep module has a small interface hiding a lot of behavior. A shallow module has an interface nearly as complex as its implementation — the abstraction isn't earning its keep.

Vocabulary

Use these terms exactly. Do not drift to synonyms.

Do not use: "component" (too vague), "service" (implies network), "API" (overloaded), "boundary" (use "seam").

The Core Diagnostic: The Deletion Test

For any module you suspect is shallow, ask:

Would deleting this module concentrate complexity into a meaningful new abstraction, or just move the same code somewhere else?

• If deleting it concentrates complexity into something better: the module was earning its keep. Leave it.
• If deleting it just relocates the same logic to callers: it was shallow. Candidate for deepening or removal.

Before Starting

1. Read CLAUDE.md and any existing architecture docs, ADRs, or CONTEXT.md
2. Walk the codebase organically — don't start with a checklist. Read the code. Note friction. Where do things feel tangled? Where does a simple change require touching many files?
3. Apply the deletion test to modules that feel off
4. Check dependency patterns — are there modules that everything depends on? Modules that depend on everything?

What to Look For

Shallow Module Symptoms

• Interface is a thin wrapper over the implementation (pass-through methods)
• Callers need to understand the implementation to use the interface correctly
• Changing the implementation always requires changing callers
• The module name describes HOW it works, not WHAT it does

Depth Opportunities

• Multiple callers doing the same multi-step sequence (logic wants to be pulled into a deeper module)
• Error handling scattered across callers instead of concentrated in one place
• Configuration or setup that every caller repeats
• Knowledge that's spread across files instead of concentrated

Dependency Classification

When proposing a deepened module, classify its dependencies:

Output

Present findings as a numbered list of deepening opportunities, ranked by leverage (highest first).

For each opportunity:

### [N]. [Module or area name]

**Files:** `path/to/file.ts`, `path/to/other.ts`
**Problem:** [What's shallow and why — be specific]
**Deletion test:** [What happens if you delete it? Concentrates or relocates?]
**Proposed deepening:** [How to make the interface smaller or the behavior richer]
**Leverage gain:** [What callers or maintainers get from this change]
**Risk:** [What could go wrong, dependencies that might break]
**Recommendation strength:** Strong / Moderate / Worth discussing

After Presenting

Do NOT propose interfaces or start coding. Present the candidates and ask which to explore. When the user picks one:

1. Enter a grilling conversation about the interface design
2. Walk the decision tree: What should the interface expose? What should it hide? What are the seams?
3. If the deepening introduces a new domain concept, suggest adding it to CONTEXT.md

Only write code after the design conversation resolves.

When to Run This

• After a burst of fast, agent-assisted development (entropy accumulates)
• When a simple feature change requires touching 5+ files
• When onboarding someone new and they can't find where things live
• When the same bug pattern keeps appearing in different places
• Periodically (every few weeks) on active codebases