rlaope/oh-my-hermes / skills/omh-frontend-refactor
omh-frontend-refactor
Verified[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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.7 KB |
| references/refactor-passes.md | markdown | 5.4 KB |
| references/state-discipline.md | markdown | 4.6 KB |
references/state-discipline.md
View on GitHub# State Discipline
The state-management review ladder for UI code. Work the sections in order:
an impossible-state fix or a derive-don't-store fix usually deletes the code a
later section would have restyled.
## 1. Make impossible states unrepresentable
Boolean flags multiply: four booleans is sixteen combinations, and most are
impossible. Replace flag clusters with one discriminated union -
`{status:'idle'} | {status:'loading'} | {status:'success', data} |
{status:'error', error}` - or a reducer whose one dispatch yields one valid
state. Escalate to an explicit state machine only when transitions carry
retries, resets, or concurrent-request races; the ladder is
`useState` -> reducer with a union -> machine, never machine-first.
## 2. Colocate, lift late, keep context slow
State lives with its consumers; wrap the consumers in a feature component that
owns it - check this before reaching for memoization. Lift state only when a
second component actually reads it. Context carries slow-changing values
(theme, locale, flags); a frequently-updated value in context re-renders every
consumer on every change. Shareable view state (filters, tabs, selection worth
a link) belongs in the URL [behavior-changing: it adds history entries and deep links].
## 3. Derive, don't sync
Never store what can be computed: a stored total beside its items drifts, and
an effect that copies props into state is a render cycle pretending to be
data flow. Compute during render; memoize only measured-expensive derivations.
## 4. Effects synchronize with the outside; they are not lifecycle
Gate question: is this effect syncing with an EXTERNAL system (socket, browser
API, third-party widget, DOM measurement, timer)? Props, state, derived
values, and user events are not external. If not external, in order:
- Deriving data -> compute inline during render.
- Responding to a user event -> the event handler, never an effect.
- Resetting state when a prop changes -> a `key` on the component [behavior-changing: it remounts the subtree and drops focus, scroll, uncontrolled input values, and child effect state].
- Fetching -> the query cache (section 5); an unavoidable fetch effect carries
a stale-response guard in its cleanup.
- Notifying a parent -> call the callback in the same handler as the setState [behavior-changing: the notification moves from after render to the event, which changes its timing].
- An effect that sets state to trigger another effect -> one handler plus
derivation; each chained effect is another full render pass.
- Subscribing to an external store -> the store-subscription hook, not manual
listeners.
A correct effect has a nameable purpose, a cleanup, and a complete dependency
list.
## 5. Server state is not UI state
Adopting a query cache is [behavior-changing]: it adds a dependency and changes
caching, deduplication, retry, and refetch-on-focus behavior. In a refactor,
name it in Notes; do not apply it.
Remote data is asynchronous, shared, and stale-able; it belongs in a query
cache (keyed queries, stale times, retry policy), not in per-component
fetch effects or a global store. Every mutation names the query keys it
invalidates. Sibling components fetching the same data independently is the
red flag that the cache is missing.
## 6. The optimistic-update contract
Adding an optimistic update is a new feature, not a refactor [behavior-changing].
This contract is the review rule for one that already exists, and the shape a
feature request must meet.
Optimistic writes come as one triple: before the request, cancel in-flight
reads, snapshot the current data, apply the optimistic value; on error,
restore the snapshot and surface the error; on settle, invalidate so the
server answer wins. An optimistic update without its rollback path, or one
that swallows the error it rolls back from, fails review.
## 7. Closing checks
Items marked [behavior-changing] in this ladder are never applied under the
refactor invariants. List each in Notes with the observable change it causes.
- Ephemeral UI state in a global store -> local state [behavior-changing: it now resets on unmount].
- The same fact stored in two places -> one owner, derive the rest.
- Prop drilling four levels or more -> context (if slow-changing) or a store
slice.
- No state reset on logout -> a root reset action plus cache clear [behavior-changing: it adds a behavior]; shared-
device data leaks are a finding, not a nit, so report it and send the fix to `omh-frontend` or a feature request.
## Boundary
A state-discipline review is prepared analysis of the code as written; it is
not a performance measurement, an executed migration, review approval, CI, or
merge evidence.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |