78 lines
3.1 KiB
Markdown
78 lines
3.1 KiB
Markdown
|
---
|
||
|
|
name: deepen
|
||
|
|
description: >
|
||
|
|
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".
|
||
|
|
concerns: [system-one-balance]
|
||
|
|
---
|
||
|
|
|
||
|
|
# 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
|
||
|
|
|
||
|
|
1. **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
|
||
|
|
|
||
|
|
1. Confirm test suite is green.
|
||
|
|
2. Scan the modules touched by the active spec or recent tasks.
|
||
|
|
3. 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:
|
||
|
|
1. **Interface Comparison**: Show concise before vs. after interface signature.
|
||
|
|
2. **Complexity Hidden**: What private decision callers no longer have to manage.
|
||
|
|
3. **Verification**: Confirm full test suite passed.
|
||
|
|
4. **Proposed Spec Edits**: Drafted lines to hand to `spec`.
|