vasily
5a19e1cd9d
- Add grill: calibrated plan stress-testing before speccing - Add spec: sole mutator of SPEC.md with format specification - Add caveman: token-compression dialect for invariants and tasks - Add review: adversarial pre-implementation refutation of spec - Add build: single-threaded plan-to-execute loop with external oracles - Add check: read-only drift detector comparing code vs invariants - Add backprop: bug-to-spec feedback loop binding regression tests - Add deepen: complexity reduction and interface shrinking pass - Format all skills to 5-phase Skill Architect anatomy with System One balance - Synchronize symlinks across OpenCode, Codex, and Claude Code
3.1 KiB
3.1 KiB
name, description, concerns
| name | description | concerns | |
|---|---|---|---|
| deepen | Codebase design improvement pass that finds shallow modules, shrinks interfaces, and pulls complexity down. Hides decisions behind clean boundaries with behavior held constant and full test suite green. Use when asked to "deepen this", "improve design", "module feels shallow", or "pull complexity down". |
|
Deepen — Make Modules Deep
Behavior is sacred: tests must be green before AND after. Every change shrinks an interface surface or hides a private decision. Deepen, don't churn.
A deep module hides substantial internal logic behind a simple interface; a shallow module's interface is nearly as complex as its implementation.
Phase 0: Setup and Protocols
- Invariants:
- Never change observable behavior during a deepening pass.
- Run only when the test suite is fully passing.
- Refactor one module per pass; deepening is surgical, never a wide codebase rewrite.
- Avoid speculative abstraction: single-use code does not need complex generalization.
Phase 1: Ingest and Check
- Confirm test suite is green.
- Scan the modules touched by the active spec or recent tasks.
- Identify shallowness symptoms:
- Pass-through methods that simply forward to another layer.
- Callers required to set 5+ configuration flags to perform a basic action.
- Leaked internal mechanisms (e.g. caller forced to know rotation policies or cache keys).
Phase 2: Processing (Core Logic)
Step 1: Diagnose Shallowness
Cite the exact defect in Caveman style with file:line:
src/auth/token.go:42: 6-arg constructor leaks rotation policy to every caller. Shallow interface.
Step 2: Design the Deeper Interface
Apply core deepening principles:
- Pull Complexity Down: Move complex parameter coordination inside the module; provide callers with a clean, obvious default.
- Define Errors Out of Existence: Structure signatures so invalid states cannot be represented or called.
- Information Hiding: Keep internal data structures private so callers never depend on implementation details.
Step 3: Propose Spec Updates
Draft changes for spec:
- New, simplified §I interface shape.
- New §V invariant preventing future regressions into shallowness.
- Targeted §T refactoring task.
Step 4: Execute & Verify Behavior
- Implement refactor behind existing tests.
- Verify test suite passes with zero failures.
- Add tests confirming backwards compatibility or clean interface boundaries.
Phase 3: The System One Balance Pass
- Augment, Don't Handcuff:
- Run only when deliberate design improvements are requested or token budget permits; never interrupt active feature delivery.
- One module per pass. Deepen the single worst offender and stop.
Phase 4: Output Execution & Verification
Deliver the deepening summary:
- Interface Comparison: Show concise before vs. after interface signature.
- Complexity Hidden: What private decision callers no longer have to manage.
- Verification: Confirm full test suite passed.
- Proposed Spec Edits: Drafted lines to hand to
spec.