laurigates/design-deep-modules

Design: Deep Modules

From A Philosophy of Software Design (Ousterhout): the best modules are deep — a small, simple interface hiding a large, complex implementation. A shallow module is the opposite: an interface nearly as complicated as the implementation it wraps, so it adds cognitive cost without removing much. This skill assesses a module or interface for depth and points at the cheapest way to deepen it.

The unit of design is complexity at the boundary: every method, parameter, and exception a caller must understand is interface cost; everything the module handles for them is the benefit. Depth is the ratio.

When to Use This Skill

| Use this skill when... | Use something else instead when... | |---|---| | Designing a new module/class/API surface and choosing what to expose | Hunting correctness bugs → code-quality-plugin:code-review | | A class boundary "feels" thin — pass-through methods, leaky config | Cyclomatic/cognitive metrics on a function → code-quality-plugin:code-complexity | | Deciding whether to split or merge two modules | Removing duplication specifically → code-quality-plugin:dry-consolidation | | Reviewing whether an abstraction earns its keep | Restructuring toward pure functions → code-quality-plugin:code-refactor |

Core Principle

| Signal of a deep module | Signal of a shallow module | |---|---| | Few public methods, many private | Public surface ≈ implementation size | | Caller passes intent, not mechanism | Caller must orchestrate internal steps | | Defaults handle the common case | Every caller re-specifies the same config | | Errors handled or masked internally | Exceptions leak the implementation's internals | | Name describes what, not how | Name encodes the mechanism (HashMapUserCache) |

Two recurring deepening moves: pull complexity downward (the module, not its callers, absorbs the hard case — a class with N callers pays once, they pay N times) and design it twice (sketch two genuinely different interfaces before committing; the second exposes the first's accidental complexity).

Parameters

Parse $ARGUMENTS:

• Target (optional, first positional) — a file, module, directory, or diff to assess. If absent, default to the current change (git diff HEAD + staged) and say so.

Execution

Execute this depth assessment:

Step 1: Map the interface vs the implementation

For the target, list the public surface (methods, params, required config, thrown exceptions, ordering constraints a caller must obey) and estimate the implementation weight behind it. State the depth verdict in one line: deep, shallow, or mixed.

Step 2: Locate the shallowness

For each shallow point, name the specific cost the caller pays and why it leaks:

• Pass-through methods that only forward to another layer (collapse the layer)
• Config a caller must always set the same way (push a default downward)
• Internal exceptions surfacing as the public contract (mask or translate)
• Ordering / temporal coupling ("call init() before run()") (encapsulate)
• Information leakage — the same design decision known in two modules

Step 3: Recommend the cheapest deepening

Per finding, give the move (pull complexity down / merge the shallow layer / add a default / design-it-twice the interface) and the resulting smaller interface. Prefer one deeper module over two shallow ones only when they share a secret; do not merge modules that are genuinely independent (that is the opposite failure — a god module).

Step 4: Report

Emit: target, depth verdict, the shallow points (ordered by caller cost), and the recommended interface change for each. Keep recommendations behaviour- preserving — this is an interface-shape review, not a rewrite.

Anti-patterns

| Mistake | Correct approach | |---|---| | Treating "more, smaller classes" as always better | Classitis makes shallow modules; depth, not count, is the goal | | Merging two modules that share no secret | That builds a god module — merge only on shared information | | Adding a config knob "for flexibility" | Each knob is interface cost paid by every caller; default it | | Exposing an exception because it was easy | Define away or mask errors the caller cannot act on |

Quick Reference

| Symptom | Deepening move | |---|---| | Pass-through / wrapper method | Collapse the layer | | Repeated caller config | Push a default downward | | Leaky exceptions | Mask or translate at the boundary | | "Call A before B" | Encapsulate the sequence | | Two interfaces both plausible | Design it twice, pick the smaller surface |

Related

• code-quality-plugin:code-complexity — function-level cyclomatic/cognitive metrics (this skill works at the interface level above that)
• code-quality-plugin:code-refactor — the mechanical moves that execute a deepening once it's chosen
• code-quality-plugin:dry-consolidation — information leakage is often duplication; dedupe is one deepening move
• software-design-plugin:design-by-contract — what the deepened interface should promise its callers