architecture-refactor

name	architecture-refactor
description	Parallel-path refactor workflow for clean boundary cutovers
user-invocable	true

Architecture-First Refactor

Use this skill when incremental edits are making structure worse, coupling is spreading, or compatibility glue is piling up.

When to Use

• A requested change crosses multiple packages or feature boundaries.
• Small edits require repeated adapters/wrappers to preserve old structure.
• A refactor has started to create duplicate roots or transitional file sprawl (for example, feature_adapter_* patterns without a clear deletion path).
• Existing package boundaries block clean naming, ownership, or test seams.

Target Outcome

• Clear package boundaries that model domain/feature ownership.
• One active implementation path after cutover.
• Meaningful tests at stable seams.
• Durable rationale promoted to docs/.

Workflow

1. Define target architecture

   • Name target packages/modules and responsibilities.
   • State explicit non-goals to prevent scope creep.
   • Identify stable contracts callers depend on.

2. Choose migration seams

   • Pick seam points (interfaces, handlers, application services) for the transition.
   • Decide what behavior must remain unchanged vs intentionally changed.

3. Build the new path in parallel

   • Implement the new package/module structure directly in the target shape.
   • Avoid mirroring legacy naming and layering into the new path.