/refactor

name: refactor
description: "Restructure code without changing observable behavior: rename, extract, inline, move, deduplicate, or replace an internal implementation with an equivalent one. Prove parity through unchanged pre-existing tests. Not for new behavior, bug fixes, explanation-only questions, or committing finished work."
argument-hint: "<surface and motivation>"

refactor

Select this owning procedure for a behavior-preserving restructure, whether requested in plain language or through `/refactor`. Entry syntax is not an additional gate; the authorized scope, parity, and verification requirements below still apply. Externally observable behavior before equals after, proven rather than assumed.

Entry boundaries

• Identify both the surface and the motivation. Phase 1 owns the precise surface

table under existing authorization. Ask only about a missing consequential scope decision.

• New behavior, including a new error path, side effect, or public method beyond

a Phase 3 seam, belongs to `/feature`. Incorrect existing behavior belongs to `/fix`.

• An explanation-only question stays in the non-mutating question-answer path,

not this editing procedure and not a required help-command detour.

• Persisting an already-completed refactor belongs to the existing commit owner at

`{{PLUGIN_ROOT}}/skills/commit-gate/SKILL.md`, with its actual authorization and gates. No commit, push, or PR is implied merely by entering this refactor procedure.

Pre-flight

Read these, or STOP and surface the gap — never guess a command or a threshold:

Resolve the selected context format through `{{PLUGIN_ROOT}}/includes/knowledge.md`. In HTML mode, read the corresponding tech-stack and coding-standards records and use `knowledge.py commands` for declared invocations. The Markdown paths below apply only in Markdown mode.

• `{{PROJECT_DIR}}/.codearbiter/CONTEXT.md` — the `stage:` frontmatter (the maturity value) and project context.
• `{{PROJECT_DIR}}/.codearbiter/tech-stack.md` — the test, coverage, lint, and type-check invocations; file layout.
• `{{PLUGIN_ROOT}}/includes/verification-boundary.md` — the required split between focused local parity proof and exhaustive exact-head hosted CI.
• `{{PROJECT_DIR}}/.codearbiter/coding-standards.md` — style, structure, naming. Required for Phase 4.

The working tree MUST be clean over the named surface before Phase 1. A dirty surface conflates the refactor diff with unrelated edits and breaks parity verification — STOP and surface it.

Phase 1 — Surface identification · gate: BLOCK

Inspect the requested refactor and record its precise surface before restructuring. Present the table and continue when the existing request covers it; no second signoff is required. Ask only about a genuinely unresolved scope or outcome:

• Files (repo-relative paths).
• Top-level symbols touched — function, class, and exported member names.
• Public method signatures within those symbols.
• External consumers — call sites in other modules.

Reject vague surfaces. "the auth module", "the user service", "some helpers in utils" are categories, not surfaces. A surface is acceptable only when a reader could grep the repo for the listed symbols and arrive at the same file set. The table is the parity contract for Phases 2–6.

Gate: a precise, complete surface table covered by existing user authorization. Resolve category-level requests through source inspection where their outcome is clear. Ask only when inspection exposes a consequential missing choice. Include necessary consumer updates within the requested restructure and record their scope.

Phase 2 — Behavioral parity coverage proof · gate: BLOCK

Prove pre-existing tests already exercise the named surface well enough to detect a behavior change, before any production code is touched. Locate every test that exercises a symbol in the surface table. Run the coverage command from `tech-stack.md` scoped to the surface files; record each metric required by the declared coverage profile and the per-symbol test evidence.

Coverage scales with the maturity value (`stage:` in `CONTEXT.md`) — the same knob as `tdd` Phase 5, using the shared threshold table `{{PLUGIN_ROOT}}/includes/maturity-coverage.md`.

Every public method in the surface table MUST have at least one direct test — transitive coverage through a higher-level integration test does not count. A public method with zero direct tests is uncovered for this gate.

Resolve the **declared coverage profile** from `tech-stack.md` against the shared `maturity-coverage.md` rule. Every required metric must clear the threshold, and the shared report-validity and critical-path evidence requirements must hold. Keep the same profile, scope and required metrics before and after the refactor. Where the surface has no coverage tooling, take the no-tooling exemption in `{{PLUGIN_ROOT}}/includes/maturity-coverage.md` — it requires QUOTING the `tech-stack.md` Coverage section that omits a command for this surface — and the per-symbol direct-test proof stands alone. Without that citation the phase STOPs rather than passing on an unverifiable claim.

If surface coverage is below the maturity threshold on any required metric, or a public method has no direct test, use the characterization/backfill approach in `{{PLUGIN_ROOT}}/skills/tdd/SKILL.md`. Add tests for the existing behavior and run them before restructuring; initially passing tests establish the baseline. Use a meaningful isolated negative control where needed to check the oracle. Record the passing post-backfill baseline, including test identities and assertions. Resume with that measured coverage and preserve the baseline assertions through implementation.

Gate: surface coverage at or above the maturity threshold on every required metric in the declared coverage profile, the shared critical-path evidence present, AND every public method backed by a direct test. Otherwise backfill via `tdd` Phase 1 before retryin