/refactoring-csharp

name: refactoring-csharp
description: Rename and refactor C# symbols in a .NET solution or multi-solution monorepo with a one-shot Roslyn CLI. Use when the user asks to rename a symbol, preview impact, update references across a solution, or refactor shared projects across several solutions.

Refactoring C# Symbols

This skill ships a Roslyn-based C# rename CLI in `src/`. It is intentionally one-shot and stateless: one call resolves the target, validates the request, and returns either a preview or an applied rename. There is no public prepare step.

Contents

• [Canonical CLI](#canonical-cli)
• [Contract](#contract)
• [How To Use It](#how-to-use-it)
• [Monorepo Directory Mode](#monorepo-directory-mode)
• [Important Behavioral Rules](#important-behavioral-rules)
• [Supported Targets](#supported-targets)
• [File Rename Nuance](#file-rename-nuance)
• [Error Handling](#error-handling)
• [Success Criteria](#success-criteria)
• [Recommended Output Style](#recommended-output-style)

Canonical CLI

If the skill was installed by `install.sh`, prefer the prebuilt CLI:

bin/csharp-refactor rename-symbol <sln|slnx|directory> <file> <line> <oldName> <newName> [dryRun=false|true]

Otherwise run the bundled source CLI from the skill directory:

dotnet run --project src/CSharpRefactoring.Cli -- rename-symbol <sln|slnx|directory> <file> <line> <oldName> <newName> [dryRun=false|true]

When invoked from outside the skill directory, use an absolute project path:

/<skill-dir>/bin/csharp-refactor rename-symbol <sln|slnx|directory> <file> <line> <oldName> <newName> [dryRun=false|true]
# or, if no prebuilt binary is installed:
dotnet run --project /path/to/refactoring-csharp/src/CSharpRefactoring.Cli -- rename-symbol <sln|slnx|directory> <file> <line> <oldName> <newName> [dryRun=false|true]

The tool project may create normal `bin/` and `obj/` directories under the skill. That is expected and useful: it lets repeated runs reuse the .NET build cache instead of rebuilding the CLI from scratch.

The target solution is not redirected to a temporary build output. The CLI opens the solution from the solution directory and lets Roslyn/MSBuild use the target project's normal build cache (`obj/`, `bin/`, or the repository's configured artifacts layout). This is intentional: it avoids creating a second cache tree for the project being refactored and lets repeated renames benefit from the project's existing MSBuild/Roslyn design-time build cache.

Contract

| Field | Required | Default | Notes | | --- | --- | --- | --- | | `solution_path` | yes | - | Absolute path to the `.sln`/`.slnx` file, or a repository directory for monorepo-wide refactoring. | | `file_path` | yes | - | Absolute path to a file inside the solution. | | `line_number` | yes | - | 1-based line number. Use the value reported by `rg -n`. | | `old_name` | yes | - | Exact current identifier on that line. This is the anchor. | | `new_name` | yes | - | Must be a valid C# identifier. | | `dry_run` | no | `false` | Apply changes by default. Preview only when explicitly set to `true`. | | `rename_overloads` | no | `false` | Keep overloads unchanged by default. | | `rename_in_strings` | no | `false` | String literals stay untouched by default. | | `rename_in_comments` | no | `true` | Comments are renamed by default. | | `rename_file` | no | `true` | Safe file move for supported named types. Never recreate the file as delete+add. |

How To Use It

1. Use `rg -n` to locate the symbol and copy the 1-based line number directly. 2. Call `rename-symbol` once without the `dryRun` argument for normal rename requests. This applies the rename. 3. Use `dryRun=true` only when the user explicitly asks for preview, when the target is ambiguous, or when the rename is unusually broad/risky and applying immediately would be irresponsible. The CLI also accepts `true`, `--dry-run`, `dryRun=false`, `false`, and `--no-dry-run`; invalid values fail fast and must never silently apply. 4. Do not run a dry run just because the tool supports it. The tool loads the solution on every call, so preview+apply doubles the cost on large projects. 5. Summarize the result by reporting the original name, new name, changed document count, total text changes, changed files, and any file move.

Monorepo Directory Mode

Use directory mode only when a repository contains multiple `.sln`/`.slnx` files or shared projects that are not all present in one normal solution. For ordinary repositories, pass the specific solution file because it is faster and avoids scanning unrelated projects.

When `solution_path` is a directory:

• Pass the repository or workspace root as `solution_path`.
• Keep `file_path` as the absolute path to the target source file.
• The tool recursively discovers `.sln`, `.slnx`, and supported project files under the directory.
• It merges them into one temporary `.slnx`, opens that aggregate solution, performs the rename, and deletes the temporary solution directory before returning.
• The temporary aggregate solution lives outside the target repository; source files and normal project build caches remain in their original locations.

Important Behavioral Rules

• The tool is stateless. It loads the solution on every call.
• If `solution_path` is a directory, the tool scans it recursively, merges discovered `.sln`, `.slnx`, and project files into one temporary `.slnx`, opens that solution, runs the rename, and deletes the temporary solution directory before returning.
• A preview does not reserve state. If the workspace changes between preview and apply, rerun the preview.
• Prefer one apply call over preview+apply when the user already asked to perform the rename.
• For a `.sln`/`.slnx` input, the tool runs Roslyn from the target solution directory. For a directory input, it runs Roslyn from that directory while opening the temporary aggregate solution. In both modes, project files stay in place and use the target projec