Deep Modules

Deep Modules

When to use

• Lens mode — apply the vocabulary and checks below to judge or shape one interface, in a design, a review, or another skill that loads this one. No subagents. A single file or function is always lens mode.
• Audit mode — scan many modules you can't eyeball in one read for shallow ones, and return a ranked findings table. Dispatches subagents; runs Audit mode.

The lens

Use these terms exactly — don't substitute "component," "service," "API," or "boundary."

• Module — anything with an interface and an implementation; scale-agnostic (function, class, package, tier-spanning slice).
• Interface — everything a caller must know to use it correctly: the signature, plus invariants, ordering, error modes, required config, performance characteristics. Broader than "API/signature."
• Implementation — the body inside the module. Distinct from Adapter: a concrete thing satisfying an interface at a seam (a Postgres repo; an in-memory fake).
• Depth — leverage at the interface: behaviour a caller or test can exercise per unit of interface it must learn. Deep = lots of behaviour behind a small interface; shallow = interface nearly as complex as the implementation.
• Seam (Feathers) — a place you can change behaviour without editing in place; where the interface lives. Where to put it is its own decision.
• Leverage — callers' payoff: one implementation pays back across N call sites and M tests.
• Locality — maintainers' payoff: change, bugs, and knowledge concentrate in one place. Fix once, fixed everywhere.

What shallow looks like — the signals an audit hunts for:

• Pass-throughs — the interface just forwards and adds nothing.
• Leaked internals — the caller must know implementation details to use it.
• Untestable except by reaching past the interface.
• Pure functions extracted only for unit-testability, while the real bugs hide in the uncovered glue that calls them — no locality.

Principles

• The deletion test. Imagine deleting the module. If its callers get simpler and nothing substantial moves into them, it was a pass-through — fold it away or deepen it. If substantial hidden work would reappear, spread across callers, it earns its keep. Relocating trivial boilerplate to N callers is not "earning its keep" — that's still shallow.
• One adapter is a hypothetical seam; two is a real one. Don't introduce a seam unless something actually varies across it.
• A finding is a candidate, not a mandate. Respect a split preserved by a recorded project decision or convention; do not re-flag it.
• Depth is leverage, not a line ratio. Reject implementation-lines-to-interface-lines metrics; they reward padding.

Deepening move by dependency — how a shallow cluster is deepened depends on what it depends on:

Audit mode

Step 1 — Scope and cluster

Confirm what to audit — the whole repo, a directory, or a named subsystem — and read the top-level structure to identify the main modules. Then split the scope into clusters by feature/subsystem (files that change together), not just by directory — so a shallow pattern duplicated across directories still lands in one brief. Two guards:

• Size. If the scope is larger than three subagents can read closely, narrow it with the user first rather than sampling a big tree and presenting it as a complete audit.
• Prior decisions. Apply the "a finding is a candidate, not a mandate" principle — respect recorded conventions and settled decisions. If the repo has a domain glossary, name modules in its vocabulary.

Step 2 — Run the fan-out via multi-agent-analysis

Invoke the multi-agent-analysis skill via the Skill tool to dispatch the subagents, merge duplicates, and apply its confidence gate and own-verdict pass — don't restate that machinery here. Take its judged findings back for Step 3 — the ranked table is the only presentation. Hand it:

• Problem: "find shallow modules in ."
• Angles: one per cluster from Step 1 (its cap-at-3, concurrent dispatch, and opus model apply).
• Per-subagent lens, relayed inline (a parent-side load doesn't reach subagents): paste the whole The lens section into each brief, plus how to size impact — S/M/L by how much leverage or locality the reshape unlocks, tagged which. Instruct each subagent to ground every finding in a named signal (the deletion-test outcome or leaked internal that shows it, not a bare assertion), and to return the Output Schema below instead of the generic Findings shape.

Step 3 — Present the ranked table

Sort multi-agent-analysis's judged findings by impact (L → S) then confidence, and render as a table — one row per finding, columns = the Output Schema fields (Module, What's shallow, Evidence, Deepening move, Impact, Confidence). Then stop — the audit is read-only.

Close with a one-line top recommendation. To pursue a finding, point the user to grill-me (stress-test the reshape) or tech-design (design it) — this skill does not carry that loop.

Output Schema

What each audit subagent returns.

Findings {
  scope: string,                   // what was audited
  findings: [ {
    module: string,                // path:symbol
    shallow: string,               // which signal, one line
    evidence: string,              // deletion-test outcome, leaked internal, or the logic N callers re-implement
    move: string,                  // the deepening reshape, per the dependency table
    impact: string,                // "S" | "M" | "L", tagged leverage | locality
    confidence: number             // 0.00–1.00 that it's genuinely shallow and the move is right
  } ],
  dropped: string[]                // findings multi-agent-analysis dropped as low-confidence or unevidenced, listed not ranked
}