# Omh Frontend Refactor > [omh] Hermes frontend refactor workflow: 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. - Skill: `rlaope/omh-frontend-refactor` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add rlaope/omh-frontend-refactor` - Raw SKILL.md: https://api.skillmd.com/api/skills/rlaope/omh-frontend-refactor/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: rlaope (https://skillmd.com/u/rlaope) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/rlaope/omh-frontend-refactor --- # 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`, `+13 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-extracted component is two coupled ones. Handoff policy: Hermes prepares the preview plan, pass order, and characterization-test gate; the apply step is coding work for the selected executor lane, and behavior preservation is claimed only from observed test runs before and after apply. Executor readiness: - When accepted work mutates code, check `executor_readiness/v1` for the selected Codex, Claude Code, Hermes, or oh-my runtime path before first dispatch. - If readiness is `missing` or `blocked`, ask the user to choose another coding agent, configure PATH, continue in Hermes, or keep a prompt/runtime handoff; retry only after that state changes. - A readiness probe is not dispatch, implementation, verification, review, CI, merge-readiness, or merge evidence. Delegation transparency: - When delegating, show the composed delegate prompt in a fenced code block in the status message; truncate a long prompt to a bounded preview ending with `... [truncated, N chars total]` — the user must see WHAT was asked, not just that something was. - Name every delegated or parallel lane's model and, when the host exposes it, its reasoning effort inline as `(model effort)` in status and briefing lines — including runtime-native subagents; when no effort is exposed, show the model alone as `(model)` rather than writing a placeholder like `unknown` beside a known model, and never emit empty parentheses. Carry token and elapsed figures the same way in these narration lines: report observed figures and omit unobserved ones — when the user asks for a figure directly, say it was not observed instead of omitting it; a rendered status-board column keeps its own `unknown` cell. - Capture a resumable session or thread id at dispatch and report it in the status message: for non-interactive Claude Code pass `--output-format json` and read `session_id` from the result (resume with `claude -p --resume `); for Codex pass `--json` and read `thread_id` (resume with `codex exec resume `, repeating `--skip-git-repo-check` outside a git repo). Never leave a delegate run with no recorded way to resume or steer it — a plain-text one-shot that hides its session id strands the work when the run stalls or times out. - Before dispatch, grant the executor session every permission the task will need — file write/edit, command/test execution, and the working directory — on the dispatch command itself, not through settings-file guesses: for non-interactive Claude Code pass `--permission-mode acceptEdits` or an explicit `--allowedTools` list (`--dangerously-skip-permissions` only inside an isolated worktree or sandbox), and the equivalent sandbox/approval flags for other CLIs. `acceptEdits: true` is not a settings key and `~/.claude/settings.local.json` is not a file Claude Code reads — user scope is `~/.claude/settings.json` and project scope is `/.claude/settings.local.json` with rules under `permissions.allow`. Prove the grant with a bounded scratch-edit probe run before the real dispatch: a permission denial in a non-interactive run recurs identically on retry, so never redispatch until a changed grant is proven, and surface an ungrantable permission as a blocker before dispatch, not after minutes of silence. Required inputs: - the target files or component, and the framework in use - current behavior evidence: tests, or the characterization checks to write first - the diff budget: micro pass only, one macro tier, or full ladder Expected outputs: - preview change plan with per-change line refs, before/after, safety reason, and category counts - impact-ordered pass selection naming what is deferred and why - characterization-test gate verdict before any macro change - apply-step handoff with the unsafe-in-isolation changes listed under notes, never half-applied Artifact expectations: - metadata-only runtime record when a wrapper or shell is available Safety rules: - Preview is the default: analyze the whole target and emit the plan before touching any file. - Outputs, side effects, and error handling stay identical; a dropped branch or weakened handler is a defect, not a simplification. - Never rename exports, change signatures, merge or split files, or alter async execution models without flagging a breaking change; cross-file renames are notes, not silent edits. - Do not refactor test files, and do not claim behavior preservation without the before/after test evidence. ## Runtime Evidence Preferred harness for this skill: `coding-handling`. ```sh omh runtime record --skill frontend-refactor --harness coding-handling --status started ``` Record observed delegation results; otherwise return `not_available` or `not_observed`. Prepared OMH routing is not execution, review, CI, merge-readiness, or merge evidence. - Treat wrapper memory/context summaries as advisory local context, not proof of opaque Hermes memory reads or changes. Preserve workflow intent and stop conditions; verify before claiming completion. Use Hermes-native subagent/delegation features when available: native subagents -> Hermes delegation when available, otherwise sequential lanes. Shared product, compatibility, topology, memory, harness, and execution rules: `omh-routing/references/skill-common-rail.md`. Load it when applicable; otherwise name an unavailable capability.