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.
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
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
- Dependency categories
- Seam discipline
- Testing strategy: replace, don't layer
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…