Batch Refactoring
Use this when many edits must preserve externally observable behavior. Stop if you
cannot name the maintenance value and the behavior that must stay unchanged.
Role-gated action
Detect capability from tools:
- Write-capable role: map scope, apply one batch, run verification.
- Read-only role: map scope and emit the refactor in the Proposed Changes contract. Apply nothing; run nothing.
Route elsewhere
Do not use this for:
- one small edit that normal coding tools can handle
- behavior changes, bug fixes, or failing checks →
fixing-code
- test-only cleanup, coverage, or TDD →
improving-tests
- review findings without edits →
reviewing-code
- target architecture design or repo-wide structural audit → architecture skills
- cosmetic churn with no maintenance value
Language references
Load the matching reference for the language being refactored:
- C# /.NET:
references/csharp.md
- Go:
references/go.md
- Java/Kotlin:
references/java-kotlin.md
- Python:
references/python.md
- Rust:
references/rust.md
- TypeScript/JavaScript:
references/typescript.md
Unsupported language: use the general workflow in this file only.
Evidence first
Before editing:
- Define goal, non-goals, preservation target, and safety gate.
- Map every affected site with text search and language-aware tools.
- For renames, moves, extracts, splits, or broad restructures, use graph tools when available:
- GitNexus dry-run rename for renames; GitNexus context, impact, and query for callers, callees, execution flows, and string/dynamic refs.
- codegraph status first; if fresh, use codegraph context or affected to size dependency/call blast radius.
- Treat stale graph indexes as no evidence. Refresh if allowed; otherwise fall back to search/LSP and report the gap.
- Check non-code references when names or paths change: config, routes, DI wiring, serialization keys, CLI entries, generated sources, scripts, and docs.
- Read representative implementation files and tests.
- Add characterization tests at the public boundary when behavior is under-specified and risk is not low.
No mapped site, no edit.
Batch rules
Good batches are small, reversible, and single-purpose:
- rename one symbol/concept and all callers
- move one module/function and its tests
- extract one cohesive responsibility behind the same public behavior
- remove one duplicate implementation after tests prove equivalence
- update one repeated pattern across mapped sites
Rules:
- Separate mechanical structure changes from logic changes.
- Do not rename many concepts while changing APIs or control flow.
- Prefer semantic refactoring tools; use precise text edits only for mapped sites.
- For public APIs, keep compatibility shims or deprecations unless the user approved a breaking change.
- Run narrow tests after each batch; run broader lint/type/test checks before the next batch or final report.
- Delete dead code exposed by the refactor. Do not hand-edit generated or vendored files unless the project regenerates them from source.
Output
Engineer:
REFACTOR COMPLETE
=================
Preservation target: <behavior that must not change>
Safety gate: <tests/checks used>
Files changed: N
Status: CLEAN | NEEDS ATTENTION
Mapping:
- <tool/search> — <key affected sites or graph gap>
Changes:
- path:line — change
Verification:
- <command> — pass/fail
Reviewer:
## Proposed Changes
Preservation target: <behavior that must not change>
Safety gate: <tests/checks the applier should run>
Mapping:
- <tool/search> — <affected sites or graph gap>
### Change 1: <brief description>
File: `path/to/file`
Action: CREATE | MODIFY | DELETE
Code:
<changed regions with enough context to locate them>
Rationale: <why this preserves behavior while improving structure>
For multi-file renames, list every mapped occurrence or explicitly mark ambiguous/unmapped references.
Failure handling
- Scope unclear: ask which files/concept and what behavior to preserve.
- Tests/checks missing for risky code: ask to add characterization tests or shrink/defer the refactor.
- Tests fail after a batch: inspect or revert that batch before continuing.
- Required behavior change appears: stop and split into refactor first, then feature/fix.
- Graph tool missing or stale: report the gap and use search/LSP evidence instead.
- Generated or vendored occurrence: skip it unless regeneration is part of the verified workflow.
1---2description: Batch behavior-preserving refactors for multi-file, repeated-pattern,3 large-file, rename, move, extract, split, or restructure work. Use for "refactor4 across files", "batch rename", "update pattern everywhere", large files (500+ lines),5 or 5+ coordinated edits in one file. NOT for single targeted edits, behavior changes6 or bug fixes (use fixing-code), test-only refactors (use improving-tests), code7 review (use reviewing-code), or architecture redesign (use architecture-design/review).8name: refactoring-code9metadata:10 source: https://skillmd.com/skills/alexei-led/refactoring-code11---1213# Batch Refactoring1415Use this when many edits must preserve externally observable behavior. Stop if you16cannot name the maintenance value and the behavior that must stay unchanged.1718## Role-gated action1920Detect capability from tools:2122- Write-capable role: map scope, apply one batch, run verification.23- Read-only role: map scope and emit the refactor in the Proposed Changes contract. Apply nothing; run nothing.2425## Route elsewhere2627Do not use this for:2829- one small edit that normal coding tools can handle30- behavior changes, bug fixes, or failing checks → `fixing-code`31- test-only cleanup, coverage, or TDD → `improving-tests`32- review findings without edits → `reviewing-code`33- target architecture design or repo-wide structural audit → architecture skills34- cosmetic churn with no maintenance value3536## Language references3738Load the matching reference for the language being refactored:3940- C# /.NET: `references/csharp.md`41- Go: `references/go.md`42- Java/Kotlin: `references/java-kotlin.md`43- Python: `references/python.md`44- Rust: `references/rust.md`45- TypeScript/JavaScript: `references/typescript.md`4647Unsupported language: use the general workflow in this file only.4849## Evidence first5051Before editing:52531. Define goal, non-goals, preservation target, and safety gate.542. Map every affected site with text search and language-aware tools.553. For renames, moves, extracts, splits, or broad restructures, use graph tools when available:56 - GitNexus dry-run rename for renames; GitNexus context, impact, and query for callers, callees, execution flows, and string/dynamic refs.57 - codegraph status first; if fresh, use codegraph context or affected to size dependency/call blast radius.584. Treat stale graph indexes as no evidence. Refresh if allowed; otherwise fall back to search/LSP and report the gap.595. Check non-code references when names or paths change: config, routes, DI wiring, serialization keys, CLI entries, generated sources, scripts, and docs.606. Read representative implementation files and tests.617. Add characterization tests at the public boundary when behavior is under-specified and risk is not low.6263No mapped site, no edit.6465## Batch rules6667Good batches are small, reversible, and single-purpose:6869- rename one symbol/concept and all callers70- move one module/function and its tests71- extract one cohesive responsibility behind the same public behavior72- remove one duplicate implementation after tests prove equivalence73- update one repeated pattern across mapped sites7475Rules:7677- Separate mechanical structure changes from logic changes.78- Do not rename many concepts while changing APIs or control flow.79- Prefer semantic refactoring tools; use precise text edits only for mapped sites.80- For public APIs, keep compatibility shims or deprecations unless the user approved a breaking change.81- Run narrow tests after each batch; run broader lint/type/test checks before the next batch or final report.82- Delete dead code exposed by the refactor. Do not hand-edit generated or vendored files unless the project regenerates them from source.8384## Output8586Engineer:8788```text89REFACTOR COMPLETE90=================91Preservation target: <behavior that must not change>92Safety gate: <tests/checks used>93Files changed: N94Status: CLEAN | NEEDS ATTENTION9596Mapping:97- <tool/search> — <key affected sites or graph gap>9899Changes:100- path:line — change101102Verification:103- <command> — pass/fail104```105106Reviewer:107108```text109## Proposed Changes110111Preservation target: <behavior that must not change>112Safety gate: <tests/checks the applier should run>113114Mapping:115- <tool/search> — <affected sites or graph gap>116117### Change 1: <brief description>118119File: `path/to/file`120Action: CREATE | MODIFY | DELETE121122Code:123<changed regions with enough context to locate them>124125Rationale: <why this preserves behavior while improving structure>126```127128For multi-file renames, list every mapped occurrence or explicitly mark ambiguous/unmapped references.129130## Failure handling131132- Scope unclear: ask which files/concept and what behavior to preserve.133- Tests/checks missing for risky code: ask to add characterization tests or shrink/defer the refactor.134- Tests fail after a batch: inspect or revert that batch before continuing.135- Required behavior change appears: stop and split into refactor first, then feature/fix.136- Graph tool missing or stale: report the gap and use search/LSP evidence instead.137- Generated or vendored occurrence: skip it unless regeneration is part of the verified workflow.