Refactoring Guide

Refactoring Guide

Principles that LLMs consistently get wrong during refactoring. This skill corrects systematic blind spots around coupling analysis, type-level design, module boundaries, and safe migration strategies.

The core problem: LLMs optimize for what code looks like (structural similarity), but good modularization optimizes for how code changes together (temporal cohesion). Every principle here addresses that gap.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use

• Refactoring tasks: Extract module, split file, reduce coupling, reorganize
• Code review: Spot smells and suggest the right fix (not the superficial one)
• Architecture decisions: Module boundaries, dependency direction, integration points
• Proactively: When you detect any signal from the Detection Heuristics table below

Workflow

When refactoring, follow this sequence:

1. Detect — Scan the code against the Detection Heuristics table. Identify which smells are present.
2. Diagnose — For each smell, read the corresponding reference file to understand the correct principle.
3. Plan — Design the refactoring using the right technique. For multi-file changes (>3 files), use the Mikado Method (see references/architecture.md).
4. Execute — Apply changes. For shared interfaces, use expand-contract (see references/tactical-moves.md).
5. Verify — Confirm the refactoring reduced the specific coupling type identified in step 1.

Detection Heuristics

Scan for these signals to identify which principle to apply:

Principle Summary

Each principle is covered in detail in references/. Read the relevant file when you encounter its smell.

Structural Coupling (references/structural-coupling.md)

1. Seam identification — Find natural seams before extracting; don't cut across them
2. Connascence spectrum — Coupling has 9 strength levels; refactor toward weaker forms
3. Stability metrics — Depend in the direction of stability (lower instability)
4. Divergent change vs. shotgun surgery — Opposites requiring opposite fixes; don't confuse them
5. Data ownership — Every data structure has one owning module; others read via contracts, never mutate
6. Volatility isolation — Wrap high-churn dependencies behind narrow stable interfaces

Type-Level Design (references/type-design.md)

1. Parse, don't validate — Parse at boundaries into typed results; never pass raw input downstream
2. Make illegal states unrepresentable — Discriminated unions over boolean/optional fields
3. Newtype / branded types — Wrap primitives with distinct types to prevent semantic confusion
4. Temporal coupling → type-state — Return new types that expose only currently-valid methods

Architecture (references/architecture.md)

1. Functional core, imperative shell — Pure functions for decisions, thin IO shell for effects
2. Anti-corruption layer — Translate external models at integration boundaries
3. Strangler fig — Incremental migration, never big-bang rewrites
4. Mikado method — For large refactors: try, record failures, revert, work bottom-up
5. Composition root — All wiring at one entry point, not scattered through modules

Module Boundaries (references/module-boundaries.md)

1. Package by feature, not layer — Vertical slicing keeps feature changes local
2. Acyclic dependencies — Module graph must be a DAG
3. Common closure — Group by reason-for-change, not technical similarity
4. Interface segregation — Don't force consumers to depend on unused exports
5. Invariant enforcement — Modules defend their own invariants; expose operations, not setters
6. Error boundary translation — Each module translates errors to its own domain vocabulary

Tactical Moves (references/tactical-moves.md)

1. Deletion as refactoring — Best refactoring often has negative line count
2. Rule of three — Wait for three instances before abstracting
3. Inline then re-extract — Flatten confused code first, then re-decompose cleanly
4. Expand-contract — For shared interfaces: add new alongside old, migrate, remove old
5. Boolean parameter prohibition — Split or use enum instead
6. Configuration as explicit dependency — Pass config, don't import globally
7. Characterization tests first — Pin behavior before refactoring
8. Conway's law alignment — Module boundaries should match team boundaries
9. Over-modularization check — Boundary must improve change isolation, not just organize files
10. Module documentation template — For each module: responsibility, ownership, dependencies, invariants, error model

Rust-Specific (references/rust-specific.md)

Read when refactoring Rust codebases. Covers visibility as architecture, public API surface control, crate vs. module boundaries, Cargo features, workspace feature unification, and dependency policy tooling.

Swift/macOS-Specific (references/swift-macos-specific.md)

Read when refactoring Swift codebases on macOS. Covers access control as architecture (package modifier), explicit import visibility (SE-0409), target/framework boundary selection, macro isolation, and API governance tooling.

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.