oh-my-skills/skills/refactor-rename/SKILL.md

---

name: refactor-rename

description: Safely replaces an identifier across text files and file or directory paths using a bundled Node.js helper. Use for class, module, package, brand, documentation, or plain-text renames that require dry-run and collision checks.

Generic Rename Refactor

Use this skill for a filesystem-wide identifier rename. It works independently of programming language, package manager, source-control system, or file extension.

The bundled helper is <skill-dir>/scripts/replace-text.mjs. It scans the current working directory recursively, updates text contents, and renames matching file and directory basenames.

Preconditions

1. Resolve <skill-dir> to this skill's directory and inspect <skill-dir>/scripts/replace-text.mjs before use.
2. Confirm the exact old and new values and the directory to scan with the user.
3. Review the dry-run output before changing anything.
4. Do not invoke --apply without explicit user confirmation.

Default Exclusions

The helper skips these directories to avoid metadata and installed dependencies:

• .git
• .hg
• .svn
• node_modules
• vendor
• dist
• target
• __pycache__

It skips symbolic links, binary files, and files that are not valid UTF-8 (reported as Skipped non-UTF-8 file; rename those manually). It processes text files regardless of extension, including .md, .txt, source files, and configuration files.

Workflow

1. Dry Run

From the directory to refactor, run:

node <skill-dir>/scripts/replace-text.mjs '<old>' '<new>'

Review every proposed content and path change. Stop if the output is broader than intended, a target path already exists, or the script reports an error.

2. Request Confirmation

Show the exact write command and explain that it changes text and physical paths:

node <skill-dir>/scripts/replace-text.mjs '<old>' '<new>' --apply

Wait for an explicit confirmation before running it.

3. Apply

After approval, run the approved command once. Do not run cleanup, staging, commits, deployments, or dependency-changing commands unless separately requested.

4. Verify

Run the same command without --apply again. It should report no remaining matches for the old value.

Then perform only the validation relevant to the affected files and explicitly declared by the target project, such as a syntax check, build, link check, or application-specific verification.

Constraints

• Keep the rename literal: do not alter similarly named but unrelated identifiers.
• Treat a matching file or directory basename as a required path rename.
• The new value cannot contain / or \ because it is also used in file and directory basenames.
• Preserve repository-specific formatting and documentation requirements when refactoring application code.