module-depth-review

Module depth review

Find shallow modules. Propose deep ones.

A shallow module has an interface nearly as complex as its implementation — it forces callers to learn a lot for little behavioural payoff. A deep module hides substantial behaviour behind a small interface. This skill audits a region of the codebase against that lens and proposes consolidations.

This is an audit skill. It produces findings and proposals — never edits. Pair with audit-vs-fix-discipline for the output discipline.

When to use

Apply when the user asks about module boundaries, file organisation, or "is this over-modularised?". Concrete triggers:

• "Is this folder doing too much / too little?"
• "Should these be one module?"
• "Too many small files for one concept"
• "The interface is as complex as the implementation"
• "Review the architecture of X" (where X is a feature or subsystem, not the whole app)

Not the right skill for:

• Tactical complexity inside a function — use simplify
• Removing dead code or orphans — use cleanup
• Whole-app architecture decisions — use the architect agent
• Pre-merge multi-file review — use architect-reviewer

Vocabulary discipline

This skill uses precise terms. Do not substitute "component," "service," "API," "boundary," or "layer" — those words drift in meaning across teams and obscure the question being asked.

The full glossary lives in @language.md. The short version:

• Module — anything with an interface and an implementation. Scale-agnostic (function, class, package, slice).
• Interface — everything a caller must know to use the module correctly. Includes signature, invariants, ordering, error modes, perf characteristics. Wider than "API".
• Depth — leverage at the interface. Lots of behaviour per unit of interface a caller must learn = deep. Interface nearly as complex as implementation = shallow.
• Seam — where the interface lives. Distinct from what sits behind it.
• Adapter — a concrete thing that satisfies an interface at a seam.
• Leverage — what callers get from depth.
• Locality — what maintainers get from depth (change concentrates in one place).