improve-codebase-architecture

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

1. Explore the codebase and note friction:

• concept spread across many files
• shallow modules
• seam-heavy coupling
• awkward tests
• hard-to-follow ownership

2. Present candidate refactors:

• cluster
• why coupled
• dependency category from REFERENCE.md
• test impact

Ask the user which candidate to pursue.

3. For the chosen candidate, write a short problem framing:

• constraints
• required dependencies
• rough grounding sketch

4. 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

5. Compare, recommend one, or propose a hybrid.

6. 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.