/refactor

name: refactor
description: Post-PR refactor pass. Sizes the diff against the remote default branch, fans out refactor-simple (and refactor-deep on large changes) as fresh subagents that run blind to each other, merges their plans once with max-severity rules, shows the merged report, and hands it to refactor-apply on the user's word. Use after a PR is open, or whenever the user asks to refactor or clean up the branch.
argument-hint: "[--size=small|large] [--plan-only]"

Refactor

One command for the post-PR quality pass. It sizes the change, runs the right analyses independently, merges once, stops for the user, then applies. It is a manual post-PR quality pass. It changes the head, so run it before QA when QA evidence must be current-head evidence.

Why the analyses run blind

Two analyses that see each other's findings converge into one opinion. Run independently, `refactor-simple` and `refactor-deep` overlap on about half their findings, the other half is complementary, and the severe correctness findings tend to come from one of them alone. So each analysis runs in a fresh subagent with no access to the other's output, and the merge happens exactly once, here, after both are done. Repeated runs on the same diff converge on the same findings, and averaging them has demoted real Criticals; one run per analysis is the rule.

Process

1. Size the change

Resolve the PR/current branch's relevant remote and that remote's default branch before running these commands. If either is ambiguous or unavailable, report the blocked comparison; do not guess a remote or silently review an empty diff. Record the resolved remote, base ref, and merge-base for helpers.

# Resolve the relevant remote from the PR/current branch configuration first.
# Set REFACTOR_REMOTE to that verified name; do not assume origin.
git remote show "$REFACTOR_REMOTE"
# Resolve its actual default branch and set BASE to the verified remote ref.
# Fetch that branch explicitly if the ref is missing/stale, then verify it.
git rev-parse --verify "$BASE^{commit}"
git diff "$(git merge-base "$BASE" HEAD)" --numstat

Also enumerate non-ignored untracked files with `git ls-files --others --exclude-standard -z`. Treat these as added files: include their full contents and handwritten line counts in sizing and analysis, applying the same generated/vendor/lockfile exclusions. Pass this file inventory to every analyzer; plain `git diff` omits it. Do not stage files to inspect them.

Merge-base to working tree, so uncommitted work counts; the remote's real default branch, not an assumed `main`.

Exclude lockfiles, generated files, and vendored directories from the count. Under ~10 hand-written files and ~500 lines is **small**; above is **large**. `--size` overrides. State the size and the file count before fanning out.

2. Fan out, independently

Use one fresh subagent per refactoring assignment. `refactor-simple`, `refactor-deep`, and `refactor-apply` are skill modes, not separate agent types. The parent orchestrates dispatch; a leaf instance cannot spawn helpers and returns to the parent at those gates. Reuse one apply instance for authorized edits and fixes, while independent reviews get fresh instances.

Each analysis runs as a separate fresh-context subagent (the available native subagent API and configured roles, one per analysis, launched together when capacity permits). Each subagent invokes its skill and returns the absolute path of the plan it wrote. Pass the skill, worktree, and parent model/effort and no-archive requirements, without another reviewer’s findings.

• **small**: `refactor-simple` only.
• **large**: `refactor-simple` and `refactor-deep`, concurrently.

For a comprehensive review or a large change needing specialist coverage, use [the specialist lenses](references/specialist-review.md). Selected scoped deep reviews replace the broad deep pass rather than duplicate it; retain the simple pass. Run applicable lenses in waves within capacity, not an unconditional all-at-once fanout. Pass an explicit read-only scope override and distinct output path to each instance. No reviewer publishes or edits code.

Each writes its own file under `./tmp/`, and reads only its own.

3. Merge once

Read every plan and produce one merged report at `./tmp/refactor-merged-[timestamp].md`. Rules, in priority order:

1. **Cluster** findings that point at the same file/area and the same underlying issue, even if worded differently. 2. **Keep the maximum severity.** A finding that is Critical in one plan and Warning in another is Critical. A reproduced defect keeps its reproduction. 3. **Sole-source findings are kept.** Corroboration is not required; the independent runs are expected to disagree, and the disagreement is signal. 4. **Tag every item** with its source (`[S]`, `[D]`, named specialist lenses, or their combination), so the reader can see who found what. 5. **Carry each plan's quality score as reported**, plus the merged Critical/Warning/Info counts. The merged report has no combined score. 6. Pre-existing-not-against-this-PR items stay in Info, unchanged.

Keep every item's `file:line`, fix, and auto-fixable flag from its source plan. The merged report is the same shape as the individual plans, so `refactor-apply` reads it unchanged.

4. Stop for the user

Run `cold-read` on the merged report first: a person reads it to decide what to change in their code. The cold-read may reorder, retitle, and clarify; severities, findings, and `file:line` stay as written. Then show it, Criticals in full, Warnings and Info summarised, with the auto-fixable and manual counts, and stop. This is the gate: nothing is applied until the user says so. `--plan-only` ends here.

Auto-fixable items are the safe class; still show them. Manual items always wait for the user's judgment on each.

5. Apply, then prove it

On the user's go, invoke `refactor-apply` on the merged report, auto-fixable