Execute Code Refactor

Execute Code Refactor

Purpose

Perform non-trivial refactors without breaking builds by planning dependency changes, applying incremental edits, and verifying continuously.

When to use

Use the execute-code-refactor skill when:

• Reorganizing file/folder structures
• Breaking large modules/components into smaller units
• Updating imports after moves
• Standardizing repeated patterns across the codebase

Avoid using the skill when:

• You only need a refactor plan (use a planning workflow)
• The task is primarily behavior changes rather than structural refactor

Inputs

• Refactor goal and success criteria (what should improve)
• Scope (which modules/features are in scope)
• Constraints (minimal diff, no behavior change, deadlines)
• Verification tools available (typecheck/build, tests, lint)

Outputs

• An approved refactor plan with ordered steps and rollback points
• A dependency map for files being moved/renamed
• A sequence of changes that keeps the codebase buildable
• Verification evidence (what was run and passed at checkpoints)

Core rules

• Before moving/renaming, you MUST identify all import sites.
• Refactors MUST be incremental; keep the codebase buildable after each checkpoint.
• Behavior-changing edits MUST be separated from structural refactors when possible.
• High-impact moves/renames MUST be approved before execution.

Steps

1) Define the objective and constraints

• Write the goal and non-goals.
• Define the acceptable risk level and the maximum scope.

2) Inventory dependencies (required)

• Use the dependency map template to capture:
  • incoming imports (who depends on the module)
  • outgoing imports (what the module depends on)
  • exported symbols and any barrel exports

3) Draft an execution plan (required)

• Break work into small steps that keep the codebase green.
• Add explicit rollback points (last known-green commit or checkpoint).

4) Approval checkpoint (required for high-impact refactors)

Before any of the following, obtain explicit approval:

• moving/renaming files used broadly
• changing public exports
• restructuring shared libraries

At approval time, provide:

• plan summary
• expected risks
• verification commands

5) Execute incrementally with checkpoints

For each step:

1. Apply the smallest change (move one file, extract one component, etc.).
2. Update imports and exports.
3. Run verification (typecheck/build; tests when applicable).
4. Record the checkpoint as “green” before proceeding.

6) Final verification and cleanup

• Run the full verification suite available (build/typecheck + tests + lint).
• Remove dead code and unused exports introduced by the refactor.

Verification

• Dependency map exists for moved/renamed modules
• Build/typecheck passes after each checkpoint
• All import sites are updated after moves/renames
• No circular dependencies introduced
• Tests pass after completion (where available)
• Approval gate respected for high-impact moves

Boundaries

• MUST NOT move files without updating all import sites
• MUST NOT mix behavior changes with structural refactors
• MUST NOT skip verification after each checkpoint
• MUST NOT introduce circular dependencies
• SHOULD NOT refactor large scopes in a single change (split into increments)
• SHOULD keep a rollback point available throughout execution

Included assets

• Templates:
  • ./templates/refactor-checklist.md
  • ./templates/dependency-map.md
• Examples: ./examples/ includes a large component extraction playbook.