refactor-apply ยท diff
git:20260924.17234b5 to git:20260924.3aceaab
31 added, 28 removed. Audit A to A.
---
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
+ # 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
+ Turns a reviewed plan into edits. Run it only when asked, on a plan the user
+ has already seen, whether shown by `refactor` or by an analysis the user ran
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
+ `./tmp/refactor-merged-*.md`. All three share one shape: Critical, Warning,
+ and 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.
+ 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 any edit, so you can tell a
+ pre-existing failure from one you caused.
- ### 2. Auto-fixable first
+ ### 2. Auto-fixable items first
- Apply every `Auto-fixable: Yes` item, grouped by file. Rules:
+ Apply every `Auto-fixable: Yes` item, grouped by file.
- - 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.
+ - Change only the lines the finding names and what the fix strictly needs.
+ The PR's scope stays the same.
+ - If a fix would alter behaviour to satisfy a convention, it is manual: move
+ it there 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.
+ introduced. Revert any item you can't make pass, and report it.
`--auto-only` stops here with a summary.
- ### 3. Manual, one at a time with the user
+ ### 3. Manual items, 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.
+ Take each `Auto-fixable: No` item in plan priority order, Critical first:
+ 1. State the finding, the proposed change, and any judgment call it needs.
+ 2. Wait for the user's answer.
+ 3. Apply it and run the checks.
+
+ The user may skip any item. Record a skipped Critical and move on.
+
### 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.
+ Leave the edits uncommitted. The user, `refactor`, or `prepare-pr` owns the
+ commit, so the diff can be reviewed 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.
+ - Trace every edit to a plan item. Skip blanket rewrites.
+ - Preserve behaviour. A behaviour change needs the user's explicit yes and a
+ test.
+ - Apply pre-existing debt marked "not against this PR" only when the user
+ names it.
- Secrets, credentials, and generated files are stop conditions.