Unity Refactor

---
name: unity-refactor
description: Plan and run a multi-file or large-scale refactor of Unity C# code so every step follows this repository's guidelines (AGENTS.md and UNITY_AGENT_CODING_GUIDELINES_EN.md §1–63). Use when asked to refactor, clean up, restructure, split God classes or MonoBehaviours, or apply the coding guidelines across many files. Not for single small edits.
argument-hint: "[area, folder, or goal]"
---

# Unity Refactor

Target: $ARGUMENTS — if empty, ask which area or goal to refactor before doing anything.

The full guide is about 2,000 lines. Do not load it whole into this session: models follow fewer rules correctly as the number of simultaneous instructions grows. The rules are enforced in two layers instead:

- while editing, you follow AGENTS.md (already loaded) and read only the guide sections the current step touches;
- after each step, the `guideline-reviewer` subagent checks the diff against the full guide in its own context, split into rule groups so no section is skipped.

## Phase 1 — Plan (no code edits)

1. **Prerequisites.** The project must be a git repository with a clean working tree; if it is not clean, ask the user to commit or stash. Record the starting commit (`git rev-parse HEAD`) — every review range starts there. Find out how to compile and test here: Unity MCP tools (`refresh_unity`, `read_console`, `run_tests`), the Unity CLI, or `dotnet build` on the Unity-generated `.sln`. If none works, tell the user that each step will need their manual check.
2. **Hotspots.** Run the hotspot command from AGENTS.md, limited to the target area. Read the top candidates.
3. **Write `REFACTOR_PLAN.md`** at the project root:
   - goal, and what is in and out of scope;
   - a candidates table: file · lines · changes in 12 months · main problems with guide section numbers (e.g. "God MonoBehaviour — §1, §13");
   - ordered steps. Each step: one refactoring kind, files touched, how behavior is pinned (test name or manual check), risks (serialized fields, scenes/prefabs, public API), status checkbox;
   - order: safety net (tests) first, then renames, then extractions and splits, then structural moves (namespaces, folders, asmdef) last.
4. **Show the plan and stop** until the user approves or edits it.

## Phase 2 — Execute one step at a time

For each step in the plan:

1. **Pin behavior:** write and run the characterization test, or state the manual check.
2. **Read the rules for this step:** `grep -n '^## ' UNITY_AGENT_CODING_GUIDELINES_EN.md`, then Read only the sections this kind of change touches.
3. **Make the change** — one refactoring kind only. Prefer IDE/Roslyn refactorings for rename, move, and extract.
4. **Verify:** compile, check console and analyzer warnings, run tests. Quote the real output.
5. **Review:** launch `guideline-reviewer` twice in parallel on this step's diff — scope `code` and scope `safety`. Fix every must-fix and re-verify. Fix should-fix items unless that would widen the step; in that case add them to the plan as new steps. If a verdict is `blocked`, stop and report to the user.
6. **Record:** tick the step in `REFACTOR_PLAN.md` with a one-line result. Commit only if the user allowed it; otherwise pause every 3–5 steps, or at the end of each feature area, so the user can review and commit.

Every 5 steps, and at the end of each feature area, also run `guideline-reviewer` with scope `architecture` on everything changed since the previous architecture review.

## Phase 3 — Finish

1. Launch `guideline-reviewer` three times in parallel — scopes `code`, `architecture`, `safety` — over the whole range from the starting commit.
2. Fix remaining must-fix items as normal steps, with verification.
3. Report: what changed in each area, the real verification output, deviations from the guidelines that were accepted and why, and ideas left out of scope.

## Stop and Ask Before

- changing behavior, even to fix an obvious bug — record it in the plan instead;
- renaming or removing serialized fields, or public APIs used by other assemblies;
- editing scenes, prefabs, or ScriptableObject assets;
- moving files in a way that could break GUID references;
- any step that fails verification twice.