improve-codebase-architecture — Architecture Improvement

• Trigger: /improve-codebase-architecture or keywords "improve architecture", "refactor architecture", "tightly coupled"
• Best for: Architecture issues, tightly coupled modules, poor testability
• Not for: Minor single-file refactors, feature development

Overview

improve-codebase-architecture analyzes codebase architecture quality, finding improvement opportunities informed by domain language (CONTEXT.md) and ADRs. It identifies tightly coupled modules, circular dependencies, and testability issues.

Trigger Conditions

improve-codebase-architecture auto-triggers when you:

• Mention "architecture improvement", "module coupling"
• Find the codebase hard to test or maintain
• Use the /improve-codebase-architecture command

Examples

Example 1: Architecture Audit

/improve-codebase-architecture Analyze the project and identify the top 3 modules needing refactoring

Example 2: Decoupling

/improve-codebase-architecture Services under src/services/ are heavily coupled — analyze dependencies and improvement plan

Example 3: Testability

/improve-codebase-architecture This project has low unit test coverage — find architecture-level blockers

Analysis Dimensions

Dimension	Focus
Module Boundaries	Alignment with domain language layers
Dependency Direction	Circular or inverted dependencies
Coupling	Module coupling type (data/control/temporal)
Testability	DI friendliness, mockability

Notes

• Architecture improvement is a gradual process — don't try to fix everything at once
• Prioritize high churn + high coupling modules (most changes, most impact)
• Small commits for each refactoring step, green tests each time
• Don't change external behavior — this is refactoring, not rewriting

Related Skills

• grill-with-docs — Validate architecture changes against domain docs
• simplify — Code-level simplification after architecture adjustments
• review — Code review after architecture changes