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: