refactor-code

Refactor Code Skill

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.

Design Principles: Deep Modules First

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:

1. Is the logic duplicated in 2+ call sites, or genuinely complex behind a simple interface? If neither → keep it inline.
2. Does the new interface hide meaningful complexity, or just relay parameters (pass-through)? Pass-through → don't create it.
3. After the change, can a developer (or agent) understand a behavior by reading fewer files? If the file count goes up → reconsider.

See references/deep-modules.md for the full rationale, shallow-module smells, and the CONTEXT.md convention.

Quick Decision Tree

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

Prerequisites

• Phase 1 analysis should exist (refactor-notes/04-project-summary.md)
• Phase 2 tests and plan should exist (refactor-notes/06-refactor-plan.md)
• If these don't exist, ask the user if they want to proceed without them (riskier) or run the prerequisite phases first

Workflow

Execute the refactoring in three passes. Commit after each pass.

Pass 1: Extract Utilities

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:

• Create a standalone function with clear naming
• Add complete type annotations
• Handle edge cases (null, undefined, empty, boundary)
• Add JSDoc/docstring documentation
• Ensure the function is pure where possible
• Update the original file to use the extracted utility

Verification: Run tests after extraction. All must pass.

Pass 2: Convert Patterns

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:

• Preserve ALL existing behavior
• Preserve ALL error handling
• Preserve ALL side effects
• Do NOT change public APIs without explicit plan approval
• Add // REVIEW comments where manual verification is needed

Verification: Run tests after conversion. All must pass.

Pass 3: Restructure and Document

• Move files to target locations per the refactor plan, grouping by domain capability (e.g., billing/, ingestion/) rather than technical layer (e.g., services/, helpers/)
• Update all import paths
• Add documentation to all exports
• Write or refresh a CONTEXT.md in each module directory touched — purpose, domain language, boundaries, invariants, key flows (template in references/deep-modules.md)
• Remove dead code, unused imports, commented-out blocks
• Apply consistent formatting

Verification: Run tests after restructuring. All must pass.

Post-Pass: Explain Your Decisions

After each pass, explain:

1. Every structural decision you made and why
2. Any places where you changed behavior (even subtly) and the reasoning
3. Alternative approaches you considered and why you chose this one
4. Assumptions you made about the codebase or requirements
5. Areas where you are least confident about the change

Migration Workflow (Cross-Language)

When converting code from one language to another (JS→TS, Python 2→3, C→Rust, Java→Kotlin):

1. Explain first: Analyze the source code and list language-specific features, platform dependencies, and constructs that don't directly translate.
2. Identify risks: Surface deprecated APIs, unsafe operations, missing equivalents, and platform-specific behavior before generating any target code.
3. Migrate iteratively:
   • First pass: generate target-language code → build → fix compilation errors
   • Second pass: replace non-idiomatic patterns with target-language best practices
   • Third pass: add proper error handling using target-language conventions
4. Test on all target platforms. Cross-language code often involves cross-platform concerns.

Create a dedicated branch for the migration (e.g., migrate/js-to-ts). Keep original code on main until migration is validated.

Output

After each pass, present:

1. Summary of changes made
2. Test results
3. Any areas flagged for manual review

After all passes, provide:

1. Complete list of files changed, created, and deleted
2. Summary of all transformations applied
3. Any remaining // REVIEW comments that need human attention

Critical Rules

• Never change behavior. The refactored code must do exactly what the original did.
• Depth over layers. Never add a layer, interface, or single-use helper that doesn't hide real complexity. When in doubt, keep the module deeper and the file count lower.
• Commit after each pass. This gives rollback points.
• Run tests between passes. Catch issues early.
• Flag uncertainty. If you're unsure about a transformation, add a // REVIEW comment.
• Watch for hallucinated imports. Verify every import statement.
• Don't refactor tests. Keep original tests running against new code. Clean up tests later.