/fec-refactoring

name: fec-refactoring
description: Use when restructuring existing frontend code while preserving observable behavior, including responsibility extraction, module movement, conditional simplification, API cleanup, or data organization. Do not use for new feature behavior, behavior-changing bug fixes, dependency or framework migrations, or proven dead-code cleanup.

Skill: Behavior-Preserving Refactoring

Purpose

Restructure live frontend code in small, evidence-backed steps while preserving the behavior users, callers, tests, routes, and integrations can observe.

Core Contract

Every execution follows these rules:

1. **Behavior Preservation** — pure refactoring intentionally changes structure, not observable behavior. 2. **Green Baseline First** — record available verification before editing. 3. **One Refactoring at a Time** — one primary structural intent per step. 4. **Verify Every Step** — run the narrowest meaningful check immediately after each step. 5. **Revert Before Repairing** — if a new regression appears, revert that step before widening the edit. 6. **Separate Refactoring from Feature Work** — behavior changes belong in a different workflow. 7. **Smallest Safe Refactoring First** — prefer the narrowest transformation that fits the evidence. 8. **Stay Within the Diff Budget** — stop when actual scope materially exceeds the planned scope.

Pure refactoring uses **GREEN → REFACTOR → GREEN**. Do not manufacture a failing behavioral test merely to make a structural change look like feature TDD.

Procedure

1. **Classify the request.** Confirm that the intended result is structural and behavior-preserving. 2. **Discover context.** Read project configuration, affected modules, public exports, routes, state boundaries, tests, and current diff. 3. **Record observable contracts.** Capture inputs, outputs, errors, side effects, UI states, events, network calls, state transitions, routes, and public APIs that matter. 4. **Establish the baseline.** Run existing narrow checks first; record pre-existing failures rather than attributing them to later edits. 5. **Diagnose structural evidence.** Identify the concrete smell or responsibility problem and check likely false positives. 6. **Build the safety net.** Reuse relevant tests; add characterization coverage only when needed to preserve existing behavior. 7. **Plan ordered micro-refactorings.** For each step record technique, rationale, prerequisites, risk, Diff Budget, verification, and rollback boundary. 8. **Apply exactly one primary transformation.** Avoid opportunistic cleanup, formatting churn, or unrelated redesign. 9. **Verify immediately.** Compare actual scope with the Diff Budget and run targeted checks. 10. **Handle regression.** Revert the current step, confirm the prior baseline, shrink or reorder the transformation, then retry only with evidence. 11. **Run broad final validation.** Escalate from targeted checks to typecheck, tests, build, E2E, accessibility, or specialty checks when relevant. 12. **Report proof strength.** Use PASS, PARTIAL, or NOT PROVEN and state remaining risk.

Risk Classification

| Risk | Typical scope | Default action | | --- | --- | --- | | `SAFE` | Local/private code, stable contracts, easy rollback | Execute with step-level verification | | `CAUTION` | Cross-module movement, shared state, imports, hooks/composables, lifecycle | Execute only with adequate safety evidence | | `DANGER` | Public API, routes, persistence, network contracts, auth, SSR/hydration, broad state or inheritance redesign | Plan and stop for explicit approval unless already authorized |

Risk is contextual. A technique name alone never proves that a change is safe.

Diff Budget

Before each executable step record:

Expected files: N
Expected functions/components: N
Expected public API changes: 0
Expected behavior changes: 0

If the actual diff materially exceeds that budget, stop and reassess instead of silently expanding into redesign.

References

• Load [principles.md](references/principles.md) for the safety rules, evidence model, and risk language.
• Load [workflow.md](references/workflow.md) for the state machine, baseline handling, rollback, and reporting contract.
• Load [when-to-refactor.md](references/when-to-refactor.md) when deciding whether restructuring is timely or should be deferred.
• Load [refactoring-vs-feature-change.md](references/refactoring-vs-feature-change.md) when ownership overlaps feature work, debugging, cleanup, migration, or review.

Constraints

• Do not alter tests merely to accept behavior changed by the refactoring.
• Do not label auth, permission, routing, persistence, protocol, or public package changes `SAFE` without specific evidence.
• Do not stack additional structural edits after a newly introduced failure.
• Do not install a new test framework automatically when the project has none.
• Do not treat line count, complexity metrics, comments, a switch, or chaining as sufficient proof of a code smell.
• Do not perform remote Git writes by default.

Expected Output

A small-step refactoring plan or implementation with explicit evidence, risk, Diff Budget, per-step verification, rollback history when applicable, and a final PASS/PARTIAL/NOT PROVEN behavior-preservation verdict.