applying-refactors

name	applying-refactors
description	Executes a refactor plan phase-by-phase on a dedicated branch with per-phase commits and mandatory reviewer checkpoints. Use when characterization-tests scaffold is complete and plan has phases ready to execute.

Applying Refactors

Overview

Applying refactors IS executing each phase as a green, bounded-size commit with an adversarial review between phases.

One branch. One commit per phase. One reviewer pass per phase. Zero silent advances. Zero phase >400 LOC unless explicitly acknowledged.

Core principle: Rollback is a first-class path, not an exception.

Routing

Pattern: Chain Handoff: user-confirmation per phase Next: verifying-refactors (after last phase green)

Task Initialization (MANDATORY)

• Subject: [applying-refactors] Task N: <action>

Tasks:

1. Verify git clean
2. Create refactor branch
3. For each phase: a. Execute edits b. Run verification command c. Dispatch refactor-phase-reviewer d. Commit phase e. Checkpoint with user
4. Handoff to verifying-refactors

Task 1: Verify git clean

Run git status --porcelain. Non-empty → abort: "Uncommitted changes exist. Commit or stash, then rerun."

Task 2: Create branch

Read plan metadata for branch_name. Run:

git checkout -b <branch_name>

Already exists → abort: "Branch exists. Delete or rename, then rerun."

Task 3: Phase loop

For each Phase N in plan (ascending):

3a. Execute edits

Apply changes per phase files and description. Edit only the listed files. Do not touch adjacent files even if tempting.

3b. Run verification

Run the phase's verification.command. Non-zero exit → stop; do not commit; diagnose. Options: rollback phase, adjust plan, abort run.

3c. Dispatch reviewer

Invoke refactor-phase-reviewer agent with:

• Phase N metadata from plan
• Diff of unstaged changes (git diff)
• test_result: stdout + exit code from the verification command (Check 4 of the reviewer requires this)

Reviewer returns APPROVED or CHANGES_REQUESTED.

CHANGES_REQUESTED → address feedback in-place, rerun verification, re-invoke reviewer. Max 2 retries → escalate to user.

3d. Commit

Per references/phase-commit-protocol.md format.

3e. Checkpoint

Print phase N summary: files changed, LOC, verification result, reviewer outcome. Ask user:

• continue → next phase
• rollback phase → git reset --hard HEAD~1, retry phase
• abort run → stop, leave branch

Task 4: Handoff

After last phase's user continue, print run summary and hand off to verifying-refactors.

Red Flags - STOP

• Editing files not listed in the phase
• Skipping reviewer dispatch
• git commit --amend during phase loop
• Running git rebase / git reset --hard outside rollback path
• Force-pushing the refactor branch
• Disabling hooks (--no-verify)
• Advancing on CHANGES_REQUESTED without addressing feedback

Common Rationalizations

Thought	Reality
"Test runner is slow — skip verification"	Green at every commit is the contract. No skip.
"Reviewer is picky, override"	Reviewer enforces the 400 LOC cap and test discipline. Overriding invalidates the plan.
"Merge plan phases for speed"	Phase boundary = rollback unit. Merging = losing rollback.
"amend to fix a typo"	Amend post-review = review bypass. New commit instead.

References

• references/phase-commit-protocol.md