From refactor-pilot
Use this skill whenever the user wants to actually refactor, rewrite, modernize, or transform existing code. Triggers include: "refactor this", "rewrite this code", "convert to hooks", "modernize this", "extract utilities", "clean up this code", "apply the refactor plan", "transform this module", or any request to change code structure while preserving behavior. Also triggers for pattern conversions like "convert class to function", "switch to async/await", "extract shared logic", or "restructure this module". Do NOT use for analysis-only tasks — use analyze-codebase for those. Do NOT use for generating tests — use generate-tests for that.
How this skill is triggered — by the user, by Claude, or both
Slash command
/refactor-pilot:refactor-codeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are performing Phase 3 (Transform) of the Refactor Pilot Framework. Your job is to
You are performing Phase 3 (Transform) of the Refactor Pilot Framework. Your job is to rewrite code according to a refactoring plan while preserving existing behavior.
Optimize for deep modules — simple interfaces hiding substantial functionality — not for small units and extra layers. Refactoring must reduce the number of files and hops needed to understand a behavior, never increase it. This matters doubly in AI-maintained codebases: every extra layer costs context tokens, navigation hops, and agent attention.
Before extracting, splitting, or introducing any abstraction, apply the Depth Test:
See references/deep-modules.md for the full rationale, shallow-module smells, and
the CONTEXT.md convention.
Does a refactor plan exist (refactor-notes/06-refactor-plan.md)?
├── NO → Ask: proceed without a plan (riskier) or run generate-tests first?
└── YES → Follow the plan
Do safety net tests exist?
├── NO → STRONGLY recommend running generate-tests first
└── YES → Run tests before starting, confirm they pass
How many files are in scope?
├── 1-10 files → Approach A: One file at a time
├── 10-50 files → Approach B: Feature-level transform
└── 50+ files → Approach C: Iterative refinement passes
What type of refactoring?
├── Extract shared logic → Start with Pass 1
├── Modernize patterns → Start with Pass 2
├── Reorganize structure → Start with Pass 3
├── Cross-language migration → Use Migration workflow below
└── Full refactor → Execute all three passes in order
refactor-notes/04-project-summary.md)refactor-notes/06-refactor-plan.md)Execute the refactoring in three passes. Commit after each pass.
Read the refactor plan and identify all shared logic to extract. Every extraction must pass the Depth Test (see Design Principles): only extract logic that is used in 2+ call sites or genuinely complex enough to deserve its own interface. Single-use, simple logic stays inline — do not create one-line wrappers or pass-through helpers. This pass also goes in reverse: inline shallow layers the plan flags for collapse.
For each extraction:
Verification: Run tests after extraction. All must pass.
Apply modern pattern conversions as specified in the refactor plan.
See references/pattern-conversions.md for language-level conversions and GoF design
pattern transformations. If refactor-notes/03c-pattern-opportunities.md exists (from
the analyze-codebase skill), use it to guide which design patterns to apply.
For detailed pattern reference, see skills/design-patterns/references/.
For each conversion:
// REVIEW comments where manual verification is neededVerification: Run tests after conversion. All must pass.
billing/, ingestion/) rather than technical layer (e.g., services/, helpers/)CONTEXT.md in each module directory touched — purpose, domain
language, boundaries, invariants, key flows (template in references/deep-modules.md)Verification: Run tests after restructuring. All must pass.
After each pass, explain:
When converting code from one language to another (JS→TS, Python 2→3, C→Rust, Java→Kotlin):
Create a dedicated branch for the migration (e.g., migrate/js-to-ts). Keep original
code on main until migration is validated.
After each pass, present:
After all passes, provide:
// REVIEW comments that need human attention// REVIEW comment.Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub guilhermevozniak/refactor-pilot-framework --plugin refactor-pilot