---
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`

It skips symbolic links and binary files. 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:

```bash
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:

```bash
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.