Refactor

/refactor — Safe Multi-File Refactoring

Orientation

Use /refactor when you need to:

• Rename a symbol, file, or module across the codebase
• Extract a function, component, hook, class, or module from existing code
• Inline a function or module back into its callers
• Move a file or set of files to a new location
• Split a large file into smaller pieces
• Merge related files into one
• Change a function signature and update all call sites

Don't use when: debugging a specific bug (use /systematic-debugging); adding new features (use /marshal or /scaffold); deleting dead code (use /marshal for a targeted cleanup).

Boundary with /organize: /refactor changes code structure within files (extract, inline, split, merge, rename) and moves files as part of those operations. Repository-wide file/directory placement, naming sweeps, and where-does-this-belong decisions are /organize.

Behavior does not change. Tests pass before and after, no new type errors — the refactoring is correct.

Commands

Protocol

Phase 1: BASELINE

Run typecheck (via node scripts/run-with-timeout.js 300 npm run typecheck) and tests. Record error/failure counts — pre-existing issues are not your responsibility, but you must not add to them. Warn if there are uncommitted changes in files you plan to modify.

Baseline established:
  Typecheck: {pass | N errors (pre-existing)}
  Tests: {pass | N failures (pre-existing) | no test suite found}
  Git: {clean | M files with uncommitted changes}

Phase 2: PLAN

Analyze the refactoring target and produce a concrete plan.

1. Identify scope: Search the codebase for every reference to the target. Use grep/search for:

   • Import statements referencing the target
   • Usage sites (function calls, type references, component usage)
   • Re-exports from index files
   • Test files that reference the target
   • Documentation or comments mentioning the target
   • Config files (e.g., route definitions, dependency injection)

2. Classify the refactoring type and apply type-specific analysis:

   Rename (symbol): all imports + usage sites + string references + dynamic access patterns (obj[key])

   Rename (file/module): all import paths + path aliases + dynamic imports + index re-exports

   Extract (function/component/module): code to extract, enclosing-scope dependencies, return values back to caller, destination file, interface design

   Move (file): every import of old path → compute new relative paths, check alias boundary changes, barrel updates

   Split (file): logical groupings, internal cross-references, which group keeps the original path, new files per group, index if needed

   Merge (files): duplicates/conflicts, import consolidation, merged file organization

3. Produce the plan — list every file that will change and what changes:

Refactoring Plan: {type} — {description}

Files to modify:
  1. {file}: {what changes and why}
  2. {file}: {what changes and why}
  ...

Files to create:
  - {file}: {extracted from where, contains what}

Files to delete:
  - {file}: {contents moved to where}

Risk assessment:
  - {any concerns: dynamic references, string-based lookups, config files}

4. If --dry-run was specified, output the plan and stop.

Phase 3: EXECUTE

Apply changes in this order to minimize intermediate breakage:

1. Create new files first (exports only, not yet imported)
2. Update importers to point to new locations/names
3. Update the source file (remove extracted code, rename, etc.)
4. Delete old files last (only after all importers are updated)
5. Update index/barrel files

Read each file before editing. Make the minimal change needed — do not reformat unrelated code.