| name | improve-codebase-architecture |
| description | Find architectural refactors that deepen modules, reduce coupling, and improve testability. |
Improve Codebase Architecture
Favor deep modules: small interfaces, large hidden complexity.
Workflow
- Explore the codebase and note friction:
- concept spread across many files
- shallow modules
- seam-heavy coupling
- awkward tests
- hard-to-follow ownership
- Present candidate refactors:
- cluster
- why coupled
- dependency category from REFERENCE.md
- test impact
Ask the user which candidate to pursue.
- For the chosen candidate, write a short problem framing:
- constraints
- required dependencies
- rough grounding sketch
- Spawn 3+ parallel interface designs with different constraints:
- minimal
- flexible
- common-case
- ports/adapters, if relevant
Each design must include:
- signature
- usage
- hidden complexity
- dependency strategy
- tradeoffs
-
Compare, recommend one, or propose a hybrid.
-
Create the GitHub refactor issue with gh issue create using REFERENCE.md.
Rules
- Explore organically. Friction is signal.
- Be opinionated.
- Do not ask for pre-review before creating the issue.