juliusbrussee/cavekit

deepen

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

Vedi sorgente

Come usare

  1. Copia il comando e controlla il pacchetto prima di installarlo nel tuo ambiente agente.
  2. Controlla strumenti, credenziali e ambienti richiesti nel documento originale.
  3. Descrivi input e risultato desiderato; confronta l’output con le fonti.
npx skills add https://github.com/juliusbrussee/cavekit --skill deepen

Prima di iniziare

  • L’installazione non include abbonamenti, quote API o accesso ai file.
  • Stelle e installazioni indicano attività, non un test indipendente di qualità o sicurezza.
Documento Skill originale

Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.

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. Moves that deepen:

  • Pull complexity down — hide the hard part inside, give callers the simple path.
  • Define errors out of existence — design the interface so the edge can't occur.
  • Information hiding — one decision, one module; callers don't learn it.
  • General-purpose interface over a pile of special-case methods.

4. PROPOSE

Draft the change as spec edits, not a silent rewrite:

  • New/simpler §I shape for the module.
  • §V that locks the deepened invariant so a future build can't re-shallow it.
  • §T refactor row(s), each citing the §V/§I it serves.

Hand to spec to write. Show the before/after interface so the user sees the shrink.

5. VERIFY BEHAVIOR HELD

Refactor ≠ rewrite. Full suite green before you start AND after. A deepening that changes behavior is a feature in disguise — stop, route through /spec + /build. New interface gets a test proving the old callers still work.

WHEN TO STOP

Done when the chosen module's interface is strictly smaller, its hidden decision no longer leaks, tests are green, and §I/§V record the new shape. One module deepened beats five churned. Budget left → pick the next shallowest, fresh pass.

BOUNDARIES

  • ⊥ change behavior. Green before, green after. Pure structure.
  • ⊥ write SPEC.md. Propose §I/§V/§T; spec writes.
  • ⊥ deepen more than one module per pass.
  • ⊥ run under deadline or mid-feature. This is the spare-budget pass.
  • ⊥ add abstraction for single-use code. A deep module earns its hiding; a speculative one is just more surface.
dallo stesso repository

Altri Skills

Tutti gli Skills
juliusbrussee
Community

caveman

Caveman encoding for SPEC.md and spec-adjacent writes. Loaded by /spec, /build, /check. Cuts tokens ~75% vs prose while staying precise. Triggers on any write to SPEC.md or when user says "caveman", "compress this", "be brief".

Installazioni / 1h
1
GitHub Stars
1,2K
Aggiornato
14 ago
juliusbrussee
Community

check

Read-only drift detector. Diffs SPEC.md against current code and reports violations grouped by severity. Writes nothing — suggests remedies via the spec or build skills but never invokes them. Triggers when the user asks to check drift, audit the spec, verify invariants, or ask whether code still matches the spec. Phrasings: "check drift", "audit the spec", "does the code still match §V", "check invariants", "spec vs code".

Installazioni / 1h
1
GitHub Stars
1,2K
Aggiornato
14 ago
juliusbrussee
Community

grill

Calibrated interrogation of a fuzzy idea before it becomes a spec. Asks one question at a time, recommends an answer, and lands each answer in §G (goal) or §C (constraints) — unknowns parked as ? items, never guessed. The cheapest place to kill a bad idea is before §T exists. Triggers when the user has a vague idea, says "grill me", "stress-test this", "challenge my plan", "interview me before I spec", or invokes /ck:grill. Defers the actual write to the spec skill.

Installazioni / 1h
1
GitHub Stars
1,2K
Aggiornato
14 ago
juliusbrussee
Community

review

Adversarial senior review of the spec before any code is written. Constructs a skeptical reviewer whose authority comes from the codebase, §R research, and live best-practice — then tries to REFUTE the spec, not rubber-stamp it. Every finding cites evidence (file:line or source); unverifiable ones are flagged. Survivors harden §V; the run ends in an explicit go / no-go gate. Triggers before building anything high-blast-radius, when the user says "review the spec", "red-team this", "is this plan

Installazioni / 1h
1
GitHub Stars
1,2K
Aggiornato
14 ago