---
name: refactor-apply
description: Applies a refactor plan written by refactor-simple, refactor-deep, or the refactor orchestrator's merged report - auto-fixable items first, then manual items one at a time with the user, verifying with the repo's own checks after each group. Use only after the user has reviewed the plan and said to apply it.
argument-hint: "<plan-path> [--auto-only]"
---

# Refactor Apply

Turns a reviewed plan into edits. Never runs unasked; the plan it consumes was
shown to the user first, by `refactor` or by the user invoking an analysis
directly.

## Input

One plan file: an individual `./tmp/simple-refactor-plan-*.md` or
`./tmp/deep-refactor-plan-*.md`, or the orchestrator's
`./tmp/refactor-merged-*.md`. All three share the same shape - Critical /
Warning / Info sections, each item with `file:line`, a fix, and an
`Auto-fixable: Yes/No` flag.

## Process

### 1. Read the plan and the repo's checks

Parse every item. Then find what "passing" means in this repository - its
lint, typecheck, and test commands from `package.json`, `Makefile`, `CLAUDE.md`
or `AGENTS.md`. Run them once before touching anything so a pre-existing
failure is not mistaken for one you caused.

### 2. Auto-fixable first

Apply every `Auto-fixable: Yes` item, grouped by file. Rules:

- Change only the lines the finding names and what the fix strictly requires.
  A refactor pass does not widen a PR's scope.
- Never alter behaviour to satisfy a convention; if a fix would, it is not
  auto-fixable - move it to manual and say why.
- After the group, run the repo's checks. Fix straightforward failures you
  introduced; revert an item you cannot make pass and report it.

`--auto-only` stops here with a summary.

### 3. Manual, one at a time with the user

For each `Auto-fixable: No` item, in plan priority order - Critical first:
state the finding, the proposed change, and any judgment call it needs; wait
for the user's answer; apply; run the checks. The user may skip any item; a
skipped Critical is recorded, not argued.

### 4. Report

```
Applied: X auto-fixable, Y manual (Z skipped by user)
Checks: [each command] PASS/FAIL
Reverted: [items that could not pass, with reason]
Left for follow-up: [skipped or out-of-scope items]
```

Do not commit. The user (or `prepare-pr`) owns the commit, and the diff should
be reviewable as its own step.

## Rules

- No blanket rewrites; every edit traces to a plan item.
- Behaviour-preserving only. If a change would alter behaviour, it needs the
  user's explicit yes and a test.
- Pre-existing debt marked "not against this PR" is not applied unless the
  user asks for it by name.
- Secrets, credentials, and generated files are stop conditions.