Skip to content
Skills Library
Programming · Review & audit

module-depth

/module-depth

Use when creating a module, reshaping an interface, placing a seam, or code keeps resisting change or tests. Not for feature work that fits the existing shape.

Repository
dami-stack ↗
Licence
MIT
Last repository change
11.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when creating a module, reshaping an interface, placing a seam, or code keeps resisting change or tests. Not for feature work that fits the existing shape.

Original author description

Use when creating a module, reshaping an interface, placing a seam, or code keeps resisting change or tests. Not for feature work that fits the existing shape.

How it works

  1. Words
  2. Rules
  3. Consolidating a cluster
  4. Steps
  5. Done when
Original SKILL.md headings · 52 lines, 539 words
SKILL.md preview
---
name: module-depth
description: "Use when creating a module, reshaping an interface, placing a seam, or code keeps resisting change or tests. Not for feature work that fits the existing shape."
user-invocable: false
---
# Module depth
Job: Give code a shape where callers learn little and changes land in one place.
Takes: a design question, or an area or history to survey.   Gives: a firm shape recommendation, or a visual survey and a chosen candidate.
Team moves: dispatch (scouts)

## Words

Use these exact words in everything this block produces.

- **Deep module** (Ousterhout): much behaviour for little to learn, at any scale. Measure depth as what a caller gets for each thing it has to learn. Line ratios don't measure it, because they reward padding.
- **Interface**: everything callers rely on to use the module safely. That means the signature plus invariants, call order, failure behaviour, configuration and speed.
- **Seam** (Feathers): the place where two pieces meet and one could be swapped. Say seam, not boundary. Where a seam sits is a design choice of its own, apart from what sits behind it.
- **Adapter**: the role of whatever fills one side of a seam, at any size.

Callers gain because they can reuse the module. Maintainers gain because a change stays in one place.

## Rules

- **Removal test.** Imagine deleting the module. If tricky logic would land on its callers, keep it. If the callers lose nothing, it only passed calls along.
- **Seams need two.** Add one only where behaviour truly differs and you can name two real implementations. Production and test usually count.
- **Tests cross the interface callers cross.** Wanting to reach past it suggests the shape is wrong. Inside, a module may hold little replaceable pieces joined by private seams. Keep those hidden from tests as well.
- **Shrink the interface.** Fewer methods, simpler parameters, dependencies taken as inputs, results returned rather than state mutated.

## Consolidating a cluster

Classify each dependency, then treat it by category.

| Dependency | Treatment |
|---|---|
| In-process logic | Merge directly |
| Has a local stand-in | Keep behind an internal seam |
| Network service you own | Ports and adapters (Cockburn), with a production and an in-memory adapter |
| Third party you don't control | Inject it and mock it |

When the merged interface has its own tests, remove the tests that targeted the old shallow pieces.

## Steps

1. Name the need: a shape question, or a search for friction. Read the glossary and decision records.
2. For a shape question, apply Words, Rules and Consolidating, and give one recommendation with its reasons in those words.
3. If the shape is in real doubt or the user asks for options, follow `design-it-twice.md`.
4. To find where structure hurts, follow `structure-survey.md`.
5. If the answer contradicts a decision record, state that openly and make the case for reopening it.

## Done when

- The output uses the words above consistently, with no synonyms for them.
- It ends in one recommendation, or in a candidate the user chose. A list of options with no pick is not an ending.
- Each proposed module passed the removal test and each proposed seam names its two implementations.
- Each dependency in a consolidation has a category and a treatment.
- A survey or design-it-twice run met the Done when in its own file.
Files in this package (3)
  • SKILL.md 3 KB
  • design-it-twice.md 2 KB
  • structure-survey.md 3 KB

Versions

The database has no other skills named module-depth.

Database snapshot: 13.11.2026 · package version 278650095cf1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100codebase-design
    Shared vocabulary for designing deep modules — interface, seam, depth. Use when designing or improving a module's interface, placing a seam, or deciding what an API hides. Don't use for codebase-wide audits (/architecture-audit), behavior-preserving cleanup (/refactor), or UI…
  • 100codebase-design
    Deep modules: module, interface, seam, depth, leverage. Use when the task adds or changes a module, an exported function or a seam, or asks to refactor or rule on a design.
  • 100design-an-interface
    Generate radically-different module or API contract designs in parallel, then compare on depth, simplicity, and ease-of-correct-use. Trigger when the user is shaping a new module surface, exploring contract options, comparing module shapes, or applying "design it twice" to a first-pass sketch.
  • 90codebase-design
    Shared vocabulary for designing deep modules — module, interface, depth, seam, adapter. Use when designing or improving a module's interface, deciding where a seam goes, hunting for deepening opportunities, or making code more testable.
  • 100generating-docs
    Generates README.md and DESIGN.md scaffolds by analyzing module structure. Use when creating documentation templates for new modules. Automatically triggered at module creation.
  • 85{setup-skill-name}
    Sets up {module-name} module in a project. Use when the user requests to 'install {module-code} module', 'configure {module-name}', or 'setup {module-name}'.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.