# Deepen

Optional design-improvement pass for when you have spare usage to drain.

- Repository: https://github.com/JuliusBrussee/cavekit (1157 stars)
- Category: Design
- License: MIT
- Last updated: 2026-08-14
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add JuliusBrussee/cavekit --skill deepen -g -a claude-code -y`
Codex: `npx skills add JuliusBrussee/cavekit --skill deepen -g -a codex -y`
Cursor: `npx skills add JuliusBrussee/cavekit --skill deepen -g -a cursor -y`
Gemini CLI: `npx skills add JuliusBrussee/cavekit --skill deepen -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add JuliusBrussee/cavekit`

## Description

Optional design-improvement pass for when you have spare usage to drain. Finds the shallowest modules in the code the spec touches, researches a deeper design, and proposes refactors that shrink interfaces and hide decisions, behavior held constant, tests green before and after. Proposes §I/§V/§T edits, never silent rewrites. Triggers when the user says "deepen this", "improve the design", "this module feels shallow", "pull complexity down", "use spare budget on the codebase", or invokes /ck:deepen. Leans on the codebase-design skill's deep-module vocabulary when present.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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).

The rest: https://github.com/JuliusBrussee/cavekit/blob/HEAD/skills/deepen/SKILL.md