deepen

Name: deepen
Author: JuliusBrussee

439installs81forks

How to install deepen?

juliusbrussee/cavekit/deepen

$npx -y skills add JuliusBrussee/cavekit --skill deepen

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# deepen — make modules deep
2
3	Behavior is sacred: tests green before AND after. Every change shrinks an interface or hides a decision — deepen, don't churn.
4
5	A deep module hides a lot behind a small interface; a shallow one's
6	interface costs as much to use as writing the code yourself. Complexity =
7	dependencies + obscurity, and it compounds. Deepen spends spare usage paying
8	that down before it becomes a §B. Run it when the build is green & you have
9	budget to drain — not under deadline.
10
11	## WHEN TO DEEPEN
12
13	- Build is green, tests pass, & you have token budget spare.
14	- A module's interface feels as complex as its implementation (shallow smell).
15	- The same change keeps touching many files (change amplification).
16	- User explicitly asks to improve design quality.
17
18	⊥ run mid-feature or under pressure. Deepen is the deliberate pass, not the reflex.
19
20	## FIVE STEPS
21
22	### 1. PICK THE SHALLOW
23	Scan the modules the spec touches. Rank by shallowness — interface surface vs
24	work done. Pick the one worst offender. Tells:
25	- Pass-through method that only forwards to one other (shallow layer).
26	- Caller must set 5 flags right to use it (config leakage).
27	- Same abstraction repeated at two layers (no information hiding).
28	- A `?` or §B that traces back to a confusing interface.
29
30	One module per pass. Deepening is surgical, ⊥ a codebase sweep.
31
32	### 2. DIAGNOSE
33	Name the design defect in caveman, citing file:line:
34	> src/auth/token.go: 6-arg ctor leaks rotation policy to every caller. shallow.
35	Complexity is real only if it shows: change amplification, high cognitive load,
36	or an unknown-unknown (caller must know a hidden fact to call it right).
37
38	### 3. RESEARCH THE DEEPENING
39	What does a deeper version look like? Pull a known pattern (hand to research
40	for the external case → §R) or derive from the codebase's own better modules.
41	Moves that deepen:
42	- Pull complexity down — hide the hard part inside, give callers the simple path.
43	- Define errors out of existence — design the interface so the edge can't occur.
44	- Information hiding — one decision, one module; callers don't learn it.
45	- General-purpose interface over a pile of special-case methods.
46
47	### 4. PROPOSE
48	Draft the change as spec edits, not a silent rewrite:
49	- New/simpler §I shape for the module.
50	- §V that locks the deepened invariant so a future build can't re-shallow it.
51	- §T refactor row(s), each citing the §V/§I it serves.
52	Hand to spec to write. Show the before/after interface so the user sees the shrink.
53
54	### 5. VERIFY BEHAVIOR HELD
55	Refactor ≠ rewrite. Full suite green before you start AND after. A deepening that
56	changes behavior is a feature in disguise — stop, route through `/spec` + `/build`.
57	New interface gets a test proving the old callers still work.
58
59	## WHEN TO STOP
60
61	Done when the chosen module's interface is strictly smaller, its hidden decision
62	no longer leaks, tests are green, and §I/§V record the new shape. One module
63	deepened beats five churned. Budget left → pick the next shallowest, fresh pass.
64
65	## BOUNDARIES
66
67	- ⊥ change behavior. Green before, green after. Pure structure.
68	- ⊥ write SPEC.md. Propose §I/§V/§T; spec writes.
69	- ⊥ deepen more than one module per pass.
70	- ⊥ run under deadline or mid-feature. This is the spare-budget pass.
71	- ⊥ add abstraction for single-use code. A deep module earns its hiding; a speculative one is just more surface.

People who liked this also viewed

6 picks

Type

deepen

439installs81forks

View on GitHub

How to install deepen?

juliusbrussee/cavekit/deepen

$npx -y skills add JuliusBrussee/cavekit --skill deepen

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# deepen — make modules deep
2
3	Behavior is sacred: tests green before AND after. Every change shrinks an interface or hides a decision — deepen, don't churn.
4
5	A deep module hides a lot behind a small interface; a shallow one's
6	interface costs as much to use as writing the code yourself. Complexity =
7	dependencies + obscurity, and it compounds. Deepen spends spare usage paying
8	that down before it becomes a §B. Run it when the build is green & you have
9	budget to drain — not under deadline.
10
11	## WHEN TO DEEPEN
12
13	- Build is green, tests pass, & you have token budget spare.
14	- A module's interface feels as complex as its implementation (shallow smell).
15	- The same change keeps touching many files (change amplification).
16	- User explicitly asks to improve design quality.
17
18	⊥ run mid-feature or under pressure. Deepen is the deliberate pass, not the reflex.
19
20	## FIVE STEPS
21
22	### 1. PICK THE SHALLOW
23	Scan the modules the spec touches. Rank by shallowness — interface surface vs
24	work done. Pick the one worst offender. Tells:
25	- Pass-through method that only forwards to one other (shallow layer).
26	- Caller must set 5 flags right to use it (config leakage).
27	- Same abstraction repeated at two layers (no information hiding).
28	- A `?` or §B that traces back to a confusing interface.
29
30	One module per pass. Deepening is surgical, ⊥ a codebase sweep.
31
32	### 2. DIAGNOSE
33	Name the design defect in caveman, citing file:line:
34	> src/auth/token.go: 6-arg ctor leaks rotation policy to every caller. shallow.
35	Complexity is real only if it shows: change amplification, high cognitive load,
36	or an unknown-unknown (caller must know a hidden fact to call it right).
37
38	### 3. RESEARCH THE DEEPENING
39	What does a deeper version look like? Pull a known pattern (hand to research
40	for the external case → §R) or derive from the codebase's own better modules.
41	Moves that deepen:
42	- Pull complexity down — hide the hard part inside, give callers the simple path.
43	- Define errors out of existence — design the interface so the edge can't occur.
44	- Information hiding — one decision, one module; callers don't learn it.
45	- General-purpose interface over a pile of special-case methods.
46
47	### 4. PROPOSE
48	Draft the change as spec edits, not a silent rewrite:
49	- New/simpler §I shape for the module.
50	- §V that locks the deepened invariant so a future build can't re-shallow it.
51	- §T refactor row(s), each citing the §V/§I it serves.
52	Hand to spec to write. Show the before/after interface so the user sees the shrink.
53
54	### 5. VERIFY BEHAVIOR HELD
55	Refactor ≠ rewrite. Full suite green before you start AND after. A deepening that
56	changes behavior is a feature in disguise — stop, route through `/spec` + `/build`.
57	New interface gets a test proving the old callers still work.
58
59	## WHEN TO STOP
60
61	Done when the chosen module's interface is strictly smaller, its hidden decision
62	no longer leaks, tests are green, and §I/§V record the new shape. One module
63	deepened beats five churned. Budget left → pick the next shallowest, fresh pass.
64
65	## BOUNDARIES
66
67	- ⊥ change behavior. Green before, green after. Pure structure.
68	- ⊥ write SPEC.md. Propose §I/§V/§T; spec writes.
69	- ⊥ deepen more than one module per pass.
70	- ⊥ run under deadline or mid-feature. This is the spare-budget pass.
71	- ⊥ add abstraction for single-use code. A deep module earns its hiding; a speculative one is just more surface.

People who liked this also viewed

6 picks

Type