improve-codebase-architecture

Goal: identify high-leverage architecture changes and sequence them safely. Use for: - tangled dependencies, leaky boundaries, or scattered logic - modules that are hard to change or test in isolation - recurring bugs that trace back to structure, not code Workflow: 1. Map the current modules, boundaries, and data flow. 2. Locate the pain: what change is consistently hard or risky. 3. Name the architectural cause, not the surface symptom. 4. Propose a target structure with clearer boundaries. 5. Sequence the move as small, independently shippable steps. 6. Define how each step is verified before the next. Look for: - deep modules with simple interfaces vs. shallow leaky ones - cyclic dependencies and god objects - business logic mixed with I/O or framework code - duplicated knowledge across layers Rules: - justify each change by a concrete pain it removes - prefer incremental migration over big-bang rewrite - keep public behavior stable unless change is the goal - do not add abstraction without a second real use