Skip to content
Skills Library
Programming · Building & coding

codebase-deepening

/codebase-deepening

Deepening shallow modules, by how their dependencies are tested. Use when the task or your plan merges, refactors or deepens shallow modules, or puts a seam, port or adapter in place.

Repository
maestro ↗
Licence
MIT
Last repository change
13.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
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.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

Deepening shallow modules, by how their dependencies are tested. Use when the task or your plan merges, refactors or deepens shallow modules, or puts a seam, port or adapter in place.

Original author description

Deepening shallow modules, by how their dependencies are tested. Use when the task or your plan merges, refactors or deepens shallow modules, or puts a seam, port or adapter in place.

How it works

  1. Dependency categories
  2. Seam discipline
  3. Testing strategy: replace, don't layer
Original SKILL.md headings · 52 lines, 385 words
SKILL.md preview
---
name: codebase-deepening
description:
  "Deepening shallow modules, by how their dependencies are tested. Use when the task or your plan merges, refactors or
  deepens shallow modules, or puts a seam, port or adapter in place."
---

# Deepening

How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in
[`codebase-design`](../codebase-design/SKILL.md): **module**, **interface**, **seam**, **adapter**.

## Dependency categories

When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is
tested across its seam.

### 1. In-process

Pure computation, in-memory state, no I/O. Always deepenable: merge the modules and test through the new interface
directly. No adapter needed.

### 2. Local-substitutable

Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in
exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the
module's external interface.

### 3. Remote but owned (Ports & Adapters)

Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam.
The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production
uses an HTTP/gRPC/queue adapter.

Recommendation shape: _"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for
testing, so the logic sits in one deep module even though it's deployed across a network."_

### 4. True external (Mock)

Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an
injected port; tests provide a mock adapter.

## Seam discipline

- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two
  adapters are justified (typically production + test). A single-adapter seam is just indirection.
- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by
  its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just
  because tests use them.

## Testing strategy: replace, don't layer

- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist; delete them.
- Write new tests at the deepened module's interface. The **interface is the test surface**.
- Tests assert on observable outcomes through the interface, not internal state.
- Tests should survive internal refactors, since they describe behaviour, not implementation. If a test has to change
  when the implementation changes, it's testing past the interface.

Versions

The database has no other skills named codebase-deepening.

Database snapshot: 13.11.2026 · package version ae04d18570f5 (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-architecture
    Designs module interfaces, deepens shallow modules, and installs enforceable repository guardrails and agent wayfinding. Use when asked to "design the architecture", "simplify our modules", "find shallow modules", "harden the repo", "gate an unattended agent fix job", or "triage…
  • 100architecture
    Use when the user asks to improve architecture, find refactoring opportunities, surface deepening opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. Surfaces shallow modules and hypothetical seams using a precise vocabulary…
  • 100improve-codebase
    Use when designing or reviewing a module's interface, deciding where a seam goes, finding shallow modules or deepening opportunities, running an architecture review, making code more testable or AI-navigable, or extracting code repeated across three or more projects into a…
  • 100deepening-review
    Surface shallow, pass-through modules as deepening candidates, then grill the chosen one interactively (Ousterhout depth/seam paradigm). Use when modules feel thin, fragmented, or hard to navigate. For whole-system structure use /architecture-review.
  • 100architecture-rescue
    Find deepening opportunities in a codebase — shallow modules, missing seams, leaky abstractions — and present them as numbered candidates ready for a grilling session before any interface is proposed. Use when the codebase feels tangled, tests are hard to write, modules feel…
  • 81architecture
    Use when the user asks to improve architecture, find refactoring opportunities, surface deepening opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. Surfaces shallow modules and hypothetical seams using a precise vocabulary…

Feedback and reports

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