| name | improve-codebase |
| description | Improve the design quality of an existing codebase by identifying fragmented logic and consolidating it into deep modules — simple interfaces hiding complex internals. Triggered by: "improve codebase", "deep module", "/improve-codebase".
|
Goal
Find scattered, related code and consolidate it into deep modules:
small, stable interfaces that absorb complexity so callers stay simple.
See references/deep-module.md for principles and diagnostics.
Phase 1 — Explore
Scan the codebase to understand the existing structure.
- Ask the user for scope (single service / layer / whole project).
- Map public interfaces and their callers.
- Note code blocks that are logically related but currently spread across different places.
- Flag areas where callers have to sequence multiple calls to complete one business action — these are the shallow spots.
Phase 2 — Find Opportunities
From the exploration, identify candidate modules to consolidate:
- Code blocks that belong together conceptually but live apart structurally.
- Interfaces whose complexity makes the system hard for humans (or AI) to navigate.
- Any boundary where the caller knows more about how than it should.
Present candidates to the user. Confirm scope before proceeding.
Phase 3 — Wrap in a Deep Module
For each confirmed candidate:
- Collect the related code blocks into one module.
- Design a simple interface — one method per business action, ≤ 2 params, verb-phrase name.
- Hide the implementation — move all sequencing, validation, and decisions inside.
- The module absorbs the complexity; callers see only the result.
Phase 4 — Create Testable Boundaries
Once the module boundary is clear:
- Write interface tests — test through the public interface only.
- Validate from outside — treat the module as a grey box: verify inputs and outputs, not internal steps.
- Humans review the interface design and test results; they do not need to audit internal implementation line-by-line.
Run all existing tests. Stop and report if any fail.
Done
Report: "Improve complete. N modules deepened, M tests added."
