deepen — make modules deep

deepen — make modules deep

Behavior is sacred: tests green before AND after. Every change shrinks an interface or hides a decision — deepen, don't churn.

A deep module hides a lot behind a small interface; a shallow one's interface costs as much to use as writing the code yourself. Complexity = dependencies + obscurity, and it compounds. Deepen spends spare usage paying that down before it becomes a §B. Run it when the build is green & you have budget to drain — not under deadline.

WHEN TO DEEPEN

• Build is green, tests pass, & you have token budget spare.
• A module's interface feels as complex as its implementation (shallow smell).
• The same change keeps touching many files (change amplification).
• User explicitly asks to improve design quality.

⊥ run mid-feature or under pressure. Deepen is the deliberate pass, not the reflex.

FIVE STEPS

1. PICK THE SHALLOW

Scan the modules the spec touches. Rank by shallowness — interface surface vs work done. Pick the one worst offender. Tells:

• Pass-through method that only forwards to one other (shallow layer).
• Caller must set 5 flags right to use it (config leakage).
• Same abstraction repeated at two layers (no information hiding).
• A ? or §B that traces back to a confusing interface.

One module per pass. Deepening is surgical, ⊥ a codebase sweep.

2. DIAGNOSE

Name the design defect in caveman, citing file:line:

src/auth/token.go: 6-arg ctor leaks rotation policy to every caller. shallow. Complexity is real only if it shows: change amplification, high cognitive load, or an unknown-unknown (caller must know a hidden fact to call it right).

3. RESEARCH THE DEEPENING

What does a deeper version look like? Pull a known pattern (hand to research for the external case → §R) or derive from the codebase's own better modules.