Skill: clawkk/state-management (version 1.0.0)

--- name: state-management description: Deep workflow for client (and hybrid) state—modeling domain vs UI state, server cache vs client store, async and consistency, DevTools, persistence, and testing. Use when choosing Redux/Zustand/Recoil/Context, fixing stale UI, or designing data flow in React/Vue/Svelte apps. --- # State Management (Deep Workflow) Most “state bugs” are **ownership** and **lifecycle** bugs: who writes, when it syncs, and what happens on failure. Guide users to **explicit models** instead of ad-hoc globals. ## When to Offer This Workflow **Trigger conditions:** - Prop drilling pain, inconsistent UI, duplicate sources of truth - Stale data after mutations; optimistic UI gone wrong - Choosing a library vs Context vs server-state library (React Query, SWR, Apollo) - SSR/hydration + client state mismatches **Initial offer:** Use **six stages**: (1) inventory state kinds, (2) assign ownership, (3) server vs client boundaries, (4) async & updates, (5) persistence & URLs, (6) testing & DevTools. Confirm **framework** and **data fetching** approach. --- ## Stage 1: Inventory State Kinds **Goal:** Classify **what** state exists before picking tools. ### Categories - **Remote/server state**: API responses, pagination, staleness—often **not** Redux-shaped - **URL state**: filters, tabs, selection when shareable/bookmarkable - **Session UI state**: modals, toggles, transient form drafts - **Client-derived**: sorted/filtered views of remote data—**avoid** storing both raw and derived as writable truths - **Global cross-cutting**: auth user, theme, feature flags—with clear **read-only** vs **mutable** rules **Exit condition:** Table of **state slices** → **source of truth** → **consumers**. --- ## Stage 2: Assign Ownership **Goal:** **One writer** per piece of truth (or strict reducer pattern). ### Rules of Thumb - **Colocate** state where it’s used if not shared—don’t globalize prematurely - **Lift** only when multiple subtrees need it or prop chains hurt **and** ownership is clear - **Avoid** copying server entities into multiple stores without sync rules **Exit condition:** For each slice: **who sets**, **who reads**, **invalidation** story. --- ## Stage 3: Server vs Client Boundaries **Goal:** Prefer **server-state libraries** for remote data; use **client stores** for true client concerns. ### Guidance - **React Query / SWR / RTK Query**: caching, dedupe, refetch, background refresh—use for HTTP JSON - **GraphQL clients**: normalized cache + mutations with **update** policies - **Redux**: great for **predictable** global client state + middleware—not every fetch response ### Anti-patterns - Storing **full API JSON** in Redux without normalization when Apollo/Query would fit - **Double fetch**: SSR then client refetch without coordination—use **hydration** patterns **Exit condition:** Remote data has **defined cache keys**, **stale time**, and **mutation** flow. --- ## Stage 4: Async & Consistency **Goal:** **Loading**, **error**, **empty**, and **retry** are first-class; **optimistic** updates are safe or scoped. ### Practices - **Optimistic UI**: rollback path; idempotent mutations; **server reconciliation** - **Ordering**: serial vs parallel requests; **race** cancellation (AbortController) - **Pagination/infinite scroll**: cursor stability; dedupe pages ### Concurrency - **Last write wins** awareness; versioning or ETags if server supports **Exit condition:** User-visible **failure modes** handled; no silent stale success. --- ## Stage 5: Persistence & URL **Goal:** Decide **what survives refresh**, **what is shareable**, and **security**. ### Options - **URL query** for filters/tabs when users share links - **localStorage/sessionStorage** for drafts—mind **XSS** risk (sensitive data → not localStorage) - **IndexedDB** for offline—complexity tax **Exit condition:** Sensitive data **never** persisted client-side inappropriately. --- ## Stage 6: Testing & DevTools **Goal:** State logic is **unit-testable**; time-travel/debug when needed. ### Practices - **Pure reducers** / small hooks for rules - **Integration tests** for critical flows with **MSW** or mock server - **DevTools**: Redux/Query panels—ensure team knows how to inspect cache --- ## Final Review Checklist - [ ] State classified: remote vs UI vs URL vs derived - [ ] Single owner per truth; invalidation clear - [ ] Server cache strategy chosen for API data - [ ] Async/error/empty/optimistic paths specified - [ ] Persistence/security boundaries respected ## Tips for Effective Guidance - **Start minimal**: Context + server-state library solves many “Redux-sized” problems. - Always ask: “**What is the source of truth** after mutation returns?” - Mention **React Strict Mode** double-invoke when debugging weird effect behavior. ## Handling Deviations - **Legacy Redux everywhere**: incremental migration—**feature modules** first, remote data to Query next. - **Non-React**: map patterns to **signals/stores** (Vue Pinia, Svelte stores) with same ownership discipline.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)