deep-modules skill
✓ VerifiedEvaluates whether a module's interface is simple relative to its implementation to prevent over-decomposition and shallow abstractions.
- GitHub stars
- 18
- Files
- 1
- Last commit
- Oct 8, 2026
- License
- MIT
- Allowed tools
- 2
What does the deep-modules skill do?
deep-modules evaluates whether a module's interface is simple relative to its implementation to prevent over-decomposition and shallow abstractions.
Summary generated from the skill's SKILL.md.
About the deep-modules skill
Evaluating whether a module's interface is simple relative to its implementation is the primary function of deep-modules. This tool helps developers identify over-decomposition and shallow abstractions that increase cognitive load. It is designed for engineers reviewing new API designs, refactoring code, or investigating why a system feels overly complex due to too many small, collaborating classes.
When an agent loads this skill, it uses the Read and Grep tools to analyze specific files or module paths provided by the user. The analysis focuses on detecting signs of classitis, pass-through methods that merely forward calls, and pass-through variables that clutter method signatures. Unlike other lenses that focus on whether layers provide different abstractions or where boundaries should exist, this skill specifically measures the return on interface cost by comparing what a caller must know against the work the module performs behind the scenes.
What an agent can do with it
- 1Identify over-decomposed codeAnalyze a codebase to find clusters of thin classes that should be merged into a single deeper module.
- 2Detect pass-through methodsFind wrapper classes where public methods exist only to forward calls to an internal dependency.
- 3Evaluate API complexityDetermine if a method signature is too complex relative to the actual logic it executes.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the deep-modules skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the deep-modules skill in Plugin
/plugin marketplace add codybrom/clairvoyance /plugin install clairvoyance@clairvoyance-plugins
Install the deep-modules skill in Claude Code
~/.claude/skills/deep-modules/SKILL.md
$ npx degit codybrom/clairvoyance/skills/deep-modules ~/.claude/skills/deep-modulesInstall the deep-modules skill in Claude Code (project)
.claude/skills/deep-modules/SKILL.md
$ npx degit codybrom/clairvoyance/skills/deep-modules .claude/skills/deep-modulesInstall the deep-modules skill in Codex
~/.agents/skills/deep-modules/SKILL.md
$ npx degit codybrom/clairvoyance/skills/deep-modules ~/.agents/skills/deep-modulesInstall the deep-modules skill in Gemini CLI
~/.gemini/skills/deep-modules/SKILL.md
$ npx degit codybrom/clairvoyance/skills/deep-modules ~/.gemini/skills/deep-modulesInstall the deep-modules skill in Claude.ai
npx degit codybrom/clairvoyance/skills/deep-modules deep-modules && zip -r deep-modules.zip deep-modules # claude.ai → Customize → Skills → + → Create skill → Upload a skill → deep-modules.zip
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablecodybrom/clairvoyance/skills/deep-modules is public and reachablegithub.com/codybrom/clairvoyance/tree/HEAD/skills/deep-modul ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-10-08github.com/codybrom/clairvoyance/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/codybrom/clairvoyance/blob/HEAD/skills/deep-modul ↗Pass
- Pre-approved tools are scopedPre-approved: Read, Grepgithub.com/codybrom/clairvoyance/blob/HEAD/skills/deep-modul ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 142 linesgithub.com/codybrom/clairvoyance/blob/HEAD/skills/deep-modul ↗Pass
SKILL.md
View on GitHubDeep Modules Review Lens
When invoked with $ARGUMENTS, focus the analysis on the specified file or module. Read the target code first, then apply the checks below.
Evaluate whether modules provide powerful functionality through simple interfaces.
When to Apply
- Reviewing a new class, module, or API design
- When a module feels like it "doesn't do enough" or has too many parameters
- When you see many small classes collaborating to do one thing
- When a method signature closely mirrors what it calls
- During refactoring to decide what to merge or deepen
Core Principles
The Depth Principle
Every module gives functionality and costs knowledge (in the form of an interface). Deep modules give a lot and ask for very little, delivering the highest return on interface cost. This is the same interface-vs-implementation-cost asymmetry pull-complexity-down's "Core Asymmetry" applies to caller burden — here it's applied to depth.
The deepest possible module can even have no interface at all. Garbage collection is the classic example: it does enormously complex work that callers never think about.
Importantly, interfaces are also bigger than they look. The visible part is the formal interface: signatures, types, and exceptions. The invisible part is the informal interface: ordering rules, side effects, performance characteristics, and thread safety assumptions. The informal interface is usually larger and more dangerous. When the invisible part goes undocumented, callers end up with dependencies they don't know exist, creating new unknown unknowns.
The Depth Test
For each module under review:
- How many things must a caller know to use this correctly?
- How much work does the module do behind that interface?
- Could a caller skip this module and do the work directly with similar effort?
If #3 is "yes," the module is shallow.
A concrete signal: if the documentation for a method would be longer than its implementation, it is shallow.
Depth Applies at Every Scale
Methods Should Be Deep Too
A method with hundreds of lines is fine if it has a simple signature and does one complete thing. Splitting into shallow pieces can unnecessarily replace one interface with many, increasing the net complexity and cognitive load to understand or maintain. Get the depth right before worrying about code length. Once a method does something useful and complete, shortening it is the easy part.
This directly contradicts the rule from Robert Martin's Clean Code that functions should be split by length alone. Shorter is generally easier to read, but once a function is down to a few dozen lines, further reduction is unlikely to help. The real question is whether splitting reduces the complexity of the system, not the function in isolation. If the pieces lose their independence and must be read together, the split made things worse.
When Long Methods Are Fine
A method with several sequential blocks is fine as one method if the blocks are relatively independent. If the blocks depend on each other, splitting them makes things harder, not easier. Readers now have to jump between methods to understand what was visible in one place.
Classitis
One of the most common errors modern developers make is over-decomposing: splitting things into too many small pieces rather than too few large ones. You can often make something deeper by combining closely related things. When unified, they might simplify each other in ways that were invisible when apart.
Signs of Classitis:
- Many classes each doing one small thing, requiring callers to compose them
- Class names that are verbs or single operations (Reader, Writer, Parser, Validator as thin wrappers)
- Deep dependency chains where each layer adds minimal abstraction
- Needing 3+ objects to do one logical operation
- Decorator chains where each layer adds one behavior and nineteen pass-throughs
The Defaults Principle
For the underlying principle, see general-vs-special's "Defaults as a Depth Tool" section.
Decorator Alternatives
Before creating a decorator class, consider:
- Add the functionality directly to the underlying class (if general-purpose or used by most callers)
- Merge the functionality with the specific use case instead of wrapping
- Merge with an existing decorator to create one deeper decorator instead of multiple shallow ones
- Implement as a standalone class independent of the base class
Pass-Through Method Audit
A pass-through method adds interface cost with zero benefit. The telltale sign is a wrapper class where most public methods just forward to an inner dependency (a membrane, not a layer). If removing the wrapper changes nothing about the caller's experience, the class has no reason to exist.
Detection
- Signature closely resembles the method it calls
- Body is mostly a single delegation call
- Removing the method wouldn't lose any logic
Fixes (in Order of Preference)
- Expose the lower-level method directly
- Redistribute functionality so each layer has a distinct job
- Merge the classes
When Legitimate
Dispatchers that route based on arguments, and multiple implementations of a shared interface and duplicate signatures with meaningfully different behavior.
Pass-Through Variables
Data threaded through a chain of signatures just to reach one deep method. Each intermediate method must be aware of the variable without using it, and adding a new pass-through variable forces changes to every signature in the chain.
Fixes (in Order of Preference)
- Shared object: if an object is already accessible to both the top and bottom methods, store the data there
- Context object: a single object holding cross-cutting state (configuration, shared subsystems, performance counters), with references stored in instance variables via constructors so it doesn't itself become a pass-through argument
- Global variable: avoids pass-through but prevents multiple instances of the system in one process. Generally avoid
Context objects are the most common solution but not ideal. Without discipline they become grab-bags of data that create non-obvious dependencies. Variables in a context should be immutable when possible.
Interface vs Implementation
If callers see the same structure they'd see without the class, the class isn't hiding anything.
Shallow — config.getString("timeout"): callers must know the key name, parse the string to a number, and handle missing values themselves. The interface mirrors the internal key-value store.
Deep — config.getTimeout(): callers get a typed value with defaults already applied. The class absorbs parsing, validation, and key naming so callers don't have to.
Interface Simplification Tactics
- Defaults: Every parameter with a sensible default is one less thing callers must specify. The common case should require no special effort from callers
- Define errors out of existence: Every eliminated exception is one less interface element
- General-purpose design: Distill to the essential operation. Special cases go in a layer above
- Pull complexity downwards: Handle edge cases internally rather than exposing them
Review Process
- List modules: Identify the classes, functions, or APIs under review
- Measure depth: For each: count interface elements vs. implementation scope
- Flag shallow modules: Any module where interface ~= implementation in complexity
- Check for classitis: Are there clusters of thin classes that should be merged?
- Audit pass-throughs: Are any methods just forwarding calls?
- Propose deepening: For each issue, recommend: merge, absorb, or eliminate
Relationship to Other Lenses
This skill asks "is the module deep enough?": does the interface justify what's behind it? abstraction-quality asks the prior question: "is the abstraction genuine?": does each layer provide a different way of thinking? A module can be deep but sit in a layer that duplicates the abstraction of its neighbor. When adjacent layers look suspiciously similar, hand off to abstraction-quality.
Red flag signals for module depth are cataloged in red-flags (Shallow Module, Pass-Through Method).
Files in this skill
1deep-modules skill questions
How do I install the deep-modules skill in Claude Code?
Run npx degit codybrom/clairvoyance/skills/deep-modules ~/.claude/skills/deep-modules. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the deep-modules skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What is a shallow module?
A module is shallow if a caller could skip it and perform the work directly with similar effort, or if the documentation for a method is longer than its implementation.