/omh-frontend-refactor

name: "omh-frontend-refactor"
description: "[omh] Oversized or tangled UI component: behavior-preserving refactor of UI code - preview the full change plan first, apply as a second explicit step, and work impact-ordered from state architecture down to naming polish. Use when the user says: frontend-refactor, front-refactor, frontend refactor, refactor this component, refactor the component, refactor my component, component refactor, react refactor."
metadata:
  hermes:
    tags: [workflow, oh-my-hermes, maintenance]
    category: maintenance
    phase: frontend-refactor
    role: handoff-guide
    quality_tier: behavior-lock-gated

Frontend Refactor

This is a Hermes-native `frontend-refactor` workflow skill.

Why This Exists

`frontend-refactor` exists so UI restructuring runs as a previewed, behavior-locked, impact-ordered process instead of ad-hoc rewrites: the plan comes before any edit, state fixes come before polish, and every change carries its safety reason.

Do Not Use When

• The target is not UI code, or the smell is generic slop, duplication, or dead code outside a component tree; use `ai-slop-cleaner`.
• The user wants new UI built or redesigned rather than restructured; use `frontend`.
• The user wants findings and a verdict without changing the code; use `code-review`.
• The restructuring crosses module boundaries or changes architecture beyond the component tree; use `refactor-plan` for the phased execution shape, or `ralplan` first when the direction itself is still contested.

Examples

Good example:

• Prompt: This dashboard component is 800 lines and has six useState booleans - refactor it without changing behavior.
• Expected behavior: Preview first: characterization-test gate, then a plan that folds the booleans into one state union, extracts along change reasons found by the scroll test, and lists per-change line refs with safety reasons; apply only as the explicit second step.
• Why: Oversized component plus flag-cluster state is exactly the impact-ordered, behavior-locked restructuring this workflow owns.

Bad example:

• Prompt: Refactor and also add the dark-mode feature while you are in there.
• Expected behavior: Split the request: the behavior-preserving refactor runs under this workflow, and the dark-mode feature is new `frontend` work planned separately.
• Why: A refactor that changes behavior cannot claim behavior preservation; mixing the two hides the feature from review.

Completion Checklist

• The preview plan was emitted before any file changed, and the apply step was an explicit second decision.
• Behavior evidence exists on both sides of apply, and unsafe-in-isolation changes are listed as notes, not half-applied.
• Pass order was impact-first and each finding names its category and safety reason.
• Out-of-scope smells were routed: generic slop to `ai-slop-cleaner`, new UI to `frontend`, verdict-only review to `code-review`.

Recovery Notes

• If no tests exist, write the characterization checks first or hand the user the smallest set to approve; do not start the macro pass on unlocked behavior.
• If a change turns out to alter behavior mid-apply, revert that change, record it as a finding, and keep the rest of the pass.
• If the component resists extraction because state is tangled, run the state ladder first and re-attempt decomposition after.

Workflow Lane

• Current lane: **Coding handoff** (`idea-to-deploy`, `llm-app-dev`, `cto-loop`, `deploy-and-monitor`, `code-review`, `build-failure-triage`, `verification-gate`, `security-safety-review`, `+28 more`) - coding owners, handoffs, review, CI, and merge evidence.
• If intent belongs to another lane, hand back to `oh-my-hermes` or name the adjacent workflow.
• Shared product, routing, compatibility, and evidence rules: `omh-routing/references/skill-common-rail.md`.

Use When

Use when existing UI code needs restructuring without behavior change - an oversized component, boolean-flag state, effect chains, prop drilling - and the user wants a previewed, pass-ordered refactor plan rather than a new build or a verdict-only review.

Strong routing signals: `frontend-refactor`, `front-refactor`, `frontend refactor`, `refactor this component`, `refactor the component`, `refactor my component`, `component refactor`, `react refactor`, `refactor this hook`, `split this component`, `split the component`, `this component is too big`, `component is too large`, `state management review`, `state management`, `state colocation`, `too many useeffects`, `useeffect cleanup`, `clean up useeffect`, `prop drilling`, `컴포넌트 리팩터링`, `컴포넌트 리팩토링`, `컴포넌트 분리`, `컴포넌트가 너무 커`, `상태 관리 정리`, `상태 관리 리뷰`, `프론트 리팩터링`, `프론트엔드 리팩터링`, `useEffect 정리`

Catalog Metadata

Category: `maintenance` Phase: `frontend-refactor` Hermes role: `handoff-guide` Quality tier: `behavior-lock-gated` Reasoning demand: `heavy`

Quality bar:

• Work the ladder impact-first: state architecture before hook patterns before decomposition before naming and style - a state fix usually deletes the code a style pass would have polished.
• Make impossible states unrepresentable before memoizing anything: flag clusters become one discriminated union or reducer, and a state machine only when transitions carry retries, resets, or races.
• Treat effects as synchronization with external systems: deriving, event responses, prop-change resets, parent notification, and effect chains each have a non-effect form named in `omh-frontend-refactor/references/state-discipline.md`.
• Run the micro pass in fixed order - dead code, naming, simplification, modernization - finishing one category before the next; the full contract is `omh-frontend-refactor/references/refactor-passes.md`.
• Gate macro changes on characterization tests written before the refactor; snapshot tests lock markup, not behavior, and do not count.
• The scroll test picks the decomposition entry point, and extraction follows independent change reasons completely - a half-extrac