interface:
  display_name: "Codebase Design"
  short_description: "Vocabulary for deep-module design"
policy:
  allow_implicit_invocation: true

# Deepening

How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in
[SKILL.md](../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. A strong deepening candidate when merging reduces total complexity; test
through the new interface directly. No adapter is 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

- Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam
  is just indirection.
- 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 — they describe behaviour, not implementation. If a test has to change when
  the implementation changes, it's testing past the interface.

## Finding deepening candidates

- Weight recently changed hot spots first: walk `git log --oneline` for recurring files and areas. Deepening pays off
  where change concentrates.
- Look for friction signals:
  - Understanding one concept requires bouncing between many small modules.
  - Interfaces are nearly as complex as their implementations.
  - Pure functions were extracted for testability while the real bugs hide in how they are called; locality is missing.
  - Code is untestable through its current interface.
- Apply the deletion test to each suspect: "Would deleting it concentrate complexity, or just move it?" Treat
  "concentrates" as the signal to deepen.

# Design It Twice

When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent
pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.

Uses the vocabulary in [SKILL.md](../SKILL.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.

## Process

### 1. Frame the problem space

Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:

- The constraints any new interface would need to satisfy
- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints
  concrete

Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in
parallel.

### 2. Spawn sub-agents

Spawn 3+ sub-agents in parallel. Each must produce a **radically different** interface for the deepened module.

Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from
[DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space
explanation in Step 1. Give each agent a different design constraint:

- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
- Agent 2: "Maximise flexibility — support many use cases and extension."
- Agent 3: "Optimise for the most common caller — make the default case trivial."
- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."

Include both [SKILL.md](../SKILL.md) vocabulary and the target project's own domain vocabulary — from its `AGENTS.md`,
glossary, or docs — so each sub-agent names things consistently with the architecture language and the project's domain
language.

Each sub-agent outputs:

1. Interface (types, methods, params — plus invariants, ordering, error modes)
2. Usage example showing how callers use it
3. What the implementation hides behind the seam
4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
5. Trade-offs — where leverage is high, where it's thin

### 3. Present and compare

Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth**
(leverage at the interface), **locality** (where change concentrates), and **seam placement**.

After comparing, give your own recommendation: which design you think is strongest and why. If elements from different
designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.