module-depth-review

Files (3)

• SKILL.md
• dependency-categories.md
• language.md

SKILL.md (first lines)

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

Use these exact words in findings. Vocabulary drift is the failure mode.

## Process

### 1. Frame the region

Confirm with the user what region is in scope: a folder, a subsystem, a feature. Don't audit the whole codebase. If unclear, ask.

### 2. Walk the region

Read the files in scope. For each module, ask the **deletion test**:

> If I deleted this module and inlined its contents into the call sites, would complexity vanish (it was a pass-through) or reappear distributed across N callers (it was earning its keep)?

If complexity vanishes → it's a shallow module candidate for consolidation.
If complexity reappears → it's earning its keep. Leave it.

Also flag:
- Concepts scattered across many small modules that mostly call each other
- Interfaces with as many methods/parameters as the implementation has lines
- Functions extracted purely for test coverage with no true locality benefit
- Tight coupling that leaks across a seam (a "boundary" the implementation routinely bypasses)
- Single-adapter ports — an interface with only one implementation is hypothetical, not a real seam

### 3. Categorise dependencies

For each shallow-module candidate, classify its dependencies — this determines the consolidation shape and testing strategy. See @dependency-categories.md for the four categories (in-process, local-substitutable, remote-owned, true-external) and the testing strategy each one implies.

Without this step, "just merge them" recommendations skip the question of how the deepened module gets tested.

### 4. Produce findings

Output template — markdown, no HTML reports:

```
## Module depth review: <region>

### Candidates for deepening

#### 1. <one-line title>

**Strength:** Strong | Worth exploring | Speculative
**Dependency category:** in-process | local-substitutable | remote-owned | true-external

**Files involved:**
- `path/a.ts`
- `path/b.ts`
- `path/c.ts`

**Current shape:**
Three shallow modules. `a.ts` exposes `parseFoo`, `b.ts` exposes `validateFoo`, `c.ts` exposes `persistFoo`. Every caller invokes all three in sequence; the only callers of each are the others plus one top-level entry point. Interfaces total 9 functions; implementations total ~80 lines.

**Deletion test result:**
Inlining each into the single top-level caller eliminates ~60 lines of glue and the 9-function surface area. Complexity doesn't reappear elsewhere — it was glue, not encapsulation.

**Proposed deep module:**
One module exposing `processFoo(input): Result`. Three private helpers inside; one public entry point.

**Wins:**
- **Leverage:** callers learn one function instead of three.
- **Locality:** changes to the parse/validate/persist sequence happen in one place.
- **Test surface:** one interface to assert against, not three.

**Diagram:**

```mermaid
graph LR
    subgraph Before
        A[parseFoo] --> B[validateFoo] --> C[persistFoo]
    end
    subgraph After
        P[processFoo]
    end
```

#### 2. <next candidate...>

### Shallow modules that are actually earning their keep

(Optional section — name modules that *looked* shallow but passed the deletion test. Useful when the user expected them flagged.)

From stuartshields/claude-setup, MIT.

More from stuartshields/claude-setup