feat(skills): import Spec-Driven Development (SDD) suite
- 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
This commit is contained in:
1 parent
4fa17b8086
commit
5a19e1cd9d
9 files changed
+772
No files matched your search
@@ -0,0 +1,78 @@
|
||||
---
|
||||
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`.
|
||||
Reference in new issue
Block a user