@yuaone/core 0.3.2 → 0.4.0

package/plugins/react/skills/bugfix.md

@@ -0,0 +1,208 @@
+# React Bugfix Skill
+
+## Identity
+- domain: react
+- type: bugfix
+- confidence: 0.85
+- persona: Senior React engineer with 8+ years of production debugging experience. Expert in React internals, reconciliation algorithm, fiber architecture, and common failure modes across CSR/SSR environments.
+
+## Known Error Patterns
+
+### 1. Hydration Mismatch
+- **symptoms**:
+  - "Text content does not match server-rendered HTML"
+  - "Hydration failed because the initial UI does not match what was rendered on the server"
+  - "There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering"
+  - Visual flicker on page load
+  - Content changes immediately after hydration
+- **causes**:
+  - Direct access to `window`, `document`, `localStorage` during render
+  - `Date.now()`, `Math.random()`, or locale-dependent formatting in render path
+  - Conditional rendering based on `typeof window !== 'undefined'`
+  - Browser extensions injecting DOM nodes
+  - Different data between server and client (stale cache, time zones)
+- **strategy**:
+  1. Move client-only code into `useEffect` so it runs only after hydration
+  2. Use `next/dynamic` with `{ ssr: false }` for client-only components
+  3. Use `suppressHydrationWarning` as a last resort (only for intentional mismatches like timestamps)
+  4. Create a `useIsClient()` hook: `const [isClient, setIsClient] = useState(false); useEffect(() => setIsClient(true), []); return isClient;`
+  5. For third-party components that access `window`, wrap in dynamic import
+- **tools**: grep, file_read, file_edit, shell_exec
+- **pitfalls**:
+  - Do NOT wrap everything in `useEffect` blindly -- this defeats SSR benefits
+  - `suppressHydrationWarning` only suppresses warnings, does not fix the actual mismatch
+  - Browser extensions (e.g., Grammarly, translation plugins) can cause hydration errors that are not your fault -- check if the issue reproduces in incognito mode
+
+### 2. useEffect Infinite Loop
+- **symptoms**:
+  - "Maximum update depth exceeded"
+  - "Too many re-renders. React limits the number of renders to prevent an infinite loop"
+  - Browser tab freezing or crashing
+  - CPU spike in devtools
+  - Rapid state updates visible in React DevTools profiler
+- **causes**:
+  - Missing dependency array: `useEffect(() => { setState(val) })` (runs every render)
+  - Object/array in dependency array: `useEffect(() => {}, [{ a: 1 }])` (new reference every render)
+  - Setting state that is also a dependency: `useEffect(() => { setCount(count + 1) }, [count])`
+  - Stale closure capturing outdated values, causing repeated updates
+  - Calling a function that creates a new reference on every render as a dependency
+- **strategy**:
+  1. Check if dependency array exists -- add `[]` for mount-only effects
+  2. Identify object/array deps -- stabilize with `useMemo` or `useCallback`
+  3. Use functional updater: `setCount(prev => prev + 1)` instead of `setCount(count + 1)`
+  4. Extract primitive values: `const { id } = obj; useEffect(() => {}, [id])` instead of `[obj]`
+  5. Use `useRef` for values that should not trigger re-renders
+  6. Consider `useReducer` for complex state logic to avoid multiple interdependent effects
+- **tools**: file_read, grep, file_edit
+- **pitfalls**:
+  - Do NOT disable `eslint-plugin-react-hooks` exhaustive-deps rule
+  - Do NOT use `// eslint-disable-next-line react-hooks/exhaustive-deps` without understanding why
+  - An empty `[]` dependency array is only correct for true mount-only effects
+
+### 3. State Not Updating
+- **symptoms**:
+  - UI does not reflect state change after `setState`
+  - `console.log` after `setState` shows old value
+  - State appears to "reset" or "revert"
+  - Conditional logic based on state executes wrong branch
+  - Multiple rapid updates only reflect the last one
+- **causes**:
+  - Direct mutation: `state.items.push(newItem); setState(state)` (same reference, no re-render)
+  - Reading state immediately after `setState` (batched, asynchronous)
+  - Derived state anti-pattern: duplicating prop into state without sync
+  - Stale closure in event handler or timer callback
+  - React 18 automatic batching grouping updates unexpectedly
+- **strategy**:
+  1. Always create new references: `setState(prev => [...prev, newItem])`
+  2. For objects: `setState(prev => ({ ...prev, [key]: value }))`
+  3. Use functional updater for sequential updates: `setCount(prev => prev + 1)`
+  4. For derived state, compute during render instead of syncing with `useEffect`
+  5. Use `flushSync` from `react-dom` only if you absolutely need synchronous updates (rare)
+  6. Consider Immer (`useImmer`) for deeply nested state mutations
+- **tools**: file_read, file_edit
+- **pitfalls**:
+  - Do NOT use `JSON.parse(JSON.stringify(state))` for deep cloning -- use structured clone or Immer
+  - Do NOT read state right after setting it and expect the new value
+  - Avoid `useEffect` to "sync" props to state -- this is almost always wrong
+
+### 4. Key Prop Issues
+- **symptoms**:
+  - "Each child in a list should have a unique 'key' prop"
+  - List items losing input focus on re-render
+  - Animations not working correctly in lists
+  - Wrong items being updated or deleted in lists
+  - Component state being shared between different list items
+- **causes**:
+  - Using array index as key: `items.map((item, i) => <Item key={i} />)`
+  - Missing key prop entirely
+  - Non-unique keys (duplicate IDs in data)
+  - Key changing on every render (e.g., `key={Math.random()}`)
+  - Key not reflecting item identity (using wrong field)
+- **strategy**:
+  1. Use a stable, unique identifier from data: `key={item.id}`
+  2. If no ID exists, generate one when creating the item (not during render)
+  3. For static lists that never reorder, index is acceptable
+  4. Use `crypto.randomUUID()` at item creation time, not render time
+  5. For compound keys: `key={\`${item.type}-${item.id}\`}`
+- **tools**: grep, file_read, file_edit
+- **pitfalls**:
+  - Index keys cause bugs when list is sorted, filtered, or items are inserted/removed
+  - `key={Math.random()}` forces remount on every render -- massive performance issue
+  - Keys must be stable across re-renders -- do NOT generate IDs in the render function
+
+### 5. Memory Leaks
+- **symptoms**:
+  - "Can't perform a React state update on an unmounted component"
+  - Increasing memory usage over time (check Performance tab)
+  - Stale data appearing after navigation
+  - Event listeners firing for unmounted components
+  - WebSocket connections staying open after unmount
+- **causes**:
+  - Missing cleanup function in `useEffect`
+  - Not aborting fetch requests on unmount
+  - Not removing event listeners (`window.addEventListener` without cleanup)
+  - Not clearing timers (`setInterval`, `setTimeout`)
+  - Subscriptions (WebSocket, EventSource) not closed on unmount
+- **strategy**:
+  1. Always return cleanup from `useEffect`:
+     ```
+     useEffect(() => {
+       const controller = new AbortController();
+       fetch(url, { signal: controller.signal });
+       return () => controller.abort();
+     }, [url]);
+     ```
+  2. Use `AbortController` for all fetch calls
+  3. Clear all timers: `return () => clearInterval(id);`
+  4. Remove event listeners: `return () => window.removeEventListener('resize', handler);`
+  5. Close WebSocket/EventSource connections in cleanup
+  6. For React 18 Strict Mode double-mount, ensure cleanup is idempotent
+- **tools**: grep, file_read, file_edit
+- **pitfalls**:
+  - React 18 Strict Mode in dev intentionally double-mounts -- this exposes leaks, do not suppress it
+  - The "unmounted component" warning was removed in React 18 but the leak still exists
+  - `AbortError` from aborted fetch is expected -- catch and ignore it
+
+### 6. Conditional Hook Call
+- **symptoms**:
+  - "React Hook is called conditionally. React Hooks must be called in the exact same order"
+  - "Rendered more hooks than during the previous render"
+  - "Rendered fewer hooks than expected"
+  - Cryptic errors after adding/removing hooks in conditionals
+- **causes**:
+  - Hook inside `if` statement or ternary
+  - Hook after early return
+  - Hook inside loop or nested function
+  - Dynamic hook calls based on props
+- **strategy**:
+  1. Move all hooks to the top level of the component, before any conditionals
+  2. Use the hook unconditionally, then conditionally use its result
+  3. For conditional effects: `useEffect(() => { if (condition) { /* ... */ } }, [condition])`
+  4. Split into separate components if hook logic is fundamentally conditional
+  5. For dynamic lists of hooks, restructure to use a single hook with array state
+- **tools**: file_read, file_edit
+- **pitfalls**:
+  - Hooks rely on call order -- React uses position to match hooks between renders
+  - Even if a condition is "always true", the linter cannot verify it -- restructure instead
+  - Custom hooks are still hooks -- they follow the same rules
+
+### 7. Stale Closure
+- **symptoms**:
+  - Event handler uses outdated state value
+  - `setTimeout`/`setInterval` callback sees initial state
+  - Click handler in a loop always captures last iteration value
+  - Async callback returns stale data after state changed
+- **causes**:
+  - Closure captures the state value at the time of creation
+  - Event handler created in a previous render still references old state
+  - Timer callback captures stale variable
+- **strategy**:
+  1. Use functional updater: `setState(prev => prev + 1)`
+  2. Use `useRef` to always have current value: `const countRef = useRef(count); countRef.current = count;`
+  3. Use `useCallback` with correct deps to recreate handler when deps change
+  4. For intervals, use a custom `useInterval` hook with ref-based callback
+  5. In event listeners, re-attach when deps change via useEffect cleanup
+- **tools**: file_read, file_edit, grep
+- **pitfalls**:
+  - Adding state to useEffect deps to fix stale closure can introduce infinite loops -- use refs for read-only access
+  - `useRef` does not trigger re-renders -- if you need both current value and re-render, combine ref + state
+
+## Tool Sequence
+1. **grep** -- Search for error pattern in source files (`**/*.tsx`, `**/*.jsx`)
+2. **file_read** -- Read the identified file(s) to understand context
+3. **grep** -- Search for related patterns (hook usage, state definitions, effect dependencies)
+4. **file_read** -- Read related files (parent components, shared hooks, store)
+5. **file_edit** -- Apply the fix with minimal changes
+6. **shell_exec** -- Run `pnpm build` or `next build` to verify no build errors
+7. **shell_exec** -- Run tests if available (`pnpm test` or `vitest run`)
+8. **grep** -- Verify the error pattern no longer exists in build output
+
+## Validation Checklist
+- [ ] Error message no longer appears in console/build output
+- [ ] `pnpm build` (or `next build`) passes without errors
+- [ ] Existing tests pass (`pnpm test`)
+- [ ] No new TypeScript errors (`tsc --noEmit`)
+- [ ] No new ESLint warnings from `react-hooks/exhaustive-deps`
+- [ ] Component renders correctly in both SSR and CSR
+- [ ] No performance regression (no unnecessary re-renders introduced)
+- [ ] Fix does not break other components that depend on the modified code

package/plugins/react/skills/component-gen.md

@@ -0,0 +1,206 @@
+# React Component Generator Skill
+
+## Identity
+- domain: react
+- type: generator
+- confidence: 0.90
+- persona: Senior React architect specializing in component design patterns, atomic design methodology, and TypeScript-first component APIs. Expert in building reusable, accessible, and testable component libraries.
+
+## Known Error Patterns
+
+### 1. Missing TypeScript Props Interface
+- **symptoms**:
+  - Props typed as `any` or missing entirely
+  - No autocomplete for component props in IDE
+  - Runtime errors from unexpected prop types
+  - `Property does not exist on type` errors
+- **causes**:
+  - Component created without explicit props type
+  - Using `React.FC` without generic parameter
+  - Props spread without type narrowing
+- **strategy**:
+  1. Define explicit interface for all props: `interface ButtonProps { ... }`
+  2. Use discriminated unions for variant props
+  3. Extend native HTML element props: `interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>`
+  4. Export props interface for consumers
+- **tools**: file_read, file_edit
+- **pitfalls**:
+  - Avoid `React.FC` -- it implicitly includes `children` in older React types and has issues with generics
+  - Do NOT use `PropsWithChildren` unless the component truly accepts arbitrary children
+
+### 2. Prop Drilling
+- **symptoms**:
+  - Same prop passed through 3+ component levels
+  - Intermediate components accept props they do not use
+  - Changing a prop signature requires editing many files
+  - `...rest` spread used to forward unknown props
+- **causes**:
+  - Flat component hierarchy without composition
+  - Missing context or state management for shared data
+  - Over-reliance on top-down data flow
+- **strategy**:
+  1. Use compound component pattern with React context
+  2. Use composition (children/render props) to skip levels
+  3. Introduce React Context for widely-shared state
+  4. Use Zustand/Jotai for cross-cutting application state
+- **tools**: file_read, grep, file_edit
+- **pitfalls**:
+  - Do NOT create a context for every piece of state -- only for truly cross-cutting concerns
+  - Context causes re-renders of all consumers -- split contexts by update frequency
+
+### 3. Missing forwardRef
+- **symptoms**:
+  - `ref` prop not working on custom component
+  - Warning: "Function components cannot be given refs"
+  - Parent cannot access child DOM node for focus management
+  - Animation libraries cannot attach to component
+- **causes**:
+  - Custom component does not use `forwardRef`
+  - ref attached to wrong inner element
+  - Generic component loses type information for ref
+- **strategy**:
+  1. Wrap with `React.forwardRef<HTMLElement, Props>((props, ref) => ...)`
+  2. Attach ref to the outermost meaningful DOM element
+  3. Use `useImperativeHandle` to expose a custom API
+  4. For generic components, use the ref-forwarding generic pattern
+- **tools**: file_read, file_edit
+- **pitfalls**:
+  - In React 19+, `ref` is a regular prop -- `forwardRef` will be unnecessary
+  - `forwardRef` breaks generic inference -- use the function overload pattern for generic components
+
+### 4. Controlled vs Uncontrolled Confusion
+- **symptoms**:
+  - "A component is changing an uncontrolled input to be controlled"
+  - Input value not updating on change
+  - Form reset not working
+  - Default value ignored after mount
+- **causes**:
+  - Switching between `value` and `defaultValue`
+  - Initial `value` is `undefined` (uncontrolled) then becomes defined (controlled)
+  - Missing `onChange` handler with `value` prop
+- **strategy**:
+  1. Choose controlled or uncontrolled and be consistent
+  2. For controlled: always pair `value` + `onChange`
+  3. For uncontrolled: use `defaultValue` + `ref`
+  4. Initialize state to empty string, not `undefined`: `useState('')`
+  5. Build components that support both modes with internal state fallback
+- **tools**: file_read, file_edit
+- **pitfalls**:
+  - `value={undefined}` makes it uncontrolled -- use `value={state ?? ''}` to stay controlled
+  - `defaultValue` is only read on mount -- changes after mount are ignored
+
+### 5. Accessibility Violations
+- **symptoms**:
+  - No keyboard navigation
+  - Screen reader cannot identify interactive elements
+  - Missing ARIA labels
+  - Focus trap not working in modals
+  - Color contrast failures
+- **causes**:
+  - Using `div` with `onClick` instead of `button`
+  - Missing `aria-label` on icon buttons
+  - Custom components not forwarding ARIA props
+  - Missing focus management in dialogs
+- **strategy**:
+  1. Use semantic HTML elements (`button`, `nav`, `main`, `dialog`)
+  2. Add `aria-label` to elements without visible text
+  3. Implement keyboard handlers: `onKeyDown` for Enter/Space/Escape
+  4. Use `role` attribute only when no semantic element exists
+  5. Trap focus in modals with `inert` attribute or focus-trap library
+- **tools**: file_read, file_edit, shell_exec
+- **pitfalls**:
+  - Do NOT add `role="button"` to a `div` when you can just use `<button>`
+  - `tabIndex={0}` alone is not enough -- also need keyboard event handlers
+
+## Component Patterns
+
+### Atomic Design Hierarchy
+```
+atoms/       -- Button, Input, Icon, Text, Badge
+molecules/   -- SearchInput, FormField, Card, MenuItem
+organisms/   -- Header, Sidebar, DataTable, Form
+templates/   -- DashboardLayout, AuthLayout
+pages/       -- HomePage, SettingsPage
+```
+
+### Compound Component Pattern
+```
+<Select>
+  <Select.Trigger />
+  <Select.Content>
+    <Select.Item value="a">Option A</Select.Item>
+    <Select.Item value="b">Option B</Select.Item>
+  </Select.Content>
+</Select>
+```
+Uses React Context internally to share state between parent and children.
+
+### Render Props / Children as Function
+```
+<DataFetcher url="/api/users">
+  {({ data, loading, error }) => (
+    loading ? <Spinner /> : <UserList users={data} />
+  )}
+</DataFetcher>
+```
+Useful for separating data logic from presentation.
+
+### Controlled + Uncontrolled Dual Mode
+```
+function Input({ value: controlledValue, defaultValue, onChange, ...props }) {
+  const [internalValue, setInternalValue] = useState(defaultValue ?? '');
+  const isControlled = controlledValue !== undefined;
+  const value = isControlled ? controlledValue : internalValue;
+
+  const handleChange = (e) => {
+    if (!isControlled) setInternalValue(e.target.value);
+    onChange?.(e);
+  };
+
+  return <input value={value} onChange={handleChange} {...props} />;
+}
+```
+
+### forwardRef + Generic Component
+```
+interface ListProps<T> {
+  items: T[];
+  renderItem: (item: T) => ReactNode;
+}
+
+function ListInner<T>(props: ListProps<T>, ref: React.ForwardedRef<HTMLUListElement>) {
+  return (
+    <ul ref={ref}>
+      {props.items.map((item, i) => (
+        <li key={i}>{props.renderItem(item)}</li>
+      ))}
+    </ul>
+  );
+}
+
+const List = React.forwardRef(ListInner) as <T>(
+  props: ListProps<T> & React.RefAttributes<HTMLUListElement>
+) => ReactElement;
+```
+
+## Tool Sequence
+1. **file_read** -- Read existing component files to understand project patterns and conventions
+2. **grep** -- Search for import patterns, style approach (CSS modules, Tailwind, styled-components)
+3. **grep** -- Search for existing similar components to maintain consistency
+4. **file_edit** -- Create the component file with proper TypeScript types, props interface, and JSDoc
+5. **file_edit** -- Create barrel export (update `index.ts`)
+6. **file_edit** -- Create test file stub with basic render test
+7. **shell_exec** -- Run `tsc --noEmit` to verify types
+8. **shell_exec** -- Run `pnpm build` to verify integration
+
+## Validation Checklist
+- [ ] Props interface is exported and fully typed (no `any`)
+- [ ] Component has JSDoc description
+- [ ] Default props use parameter defaults, not `defaultProps`
+- [ ] `forwardRef` is used if component wraps a DOM element
+- [ ] Semantic HTML elements used (not div-soup)
+- [ ] ARIA attributes present for interactive elements
+- [ ] Component handles all required variants/states
+- [ ] Barrel export updated (`index.ts`)
+- [ ] `tsc --noEmit` passes
+- [ ] `pnpm build` passes

package/plugins/react/skills/hook-extract.md

@@ -0,0 +1,208 @@
+# React Hook Extraction Skill
+
+## Identity
+- domain: react
+- type: refactor
+- confidence: 0.80
+- persona: Senior React developer specializing in hook architecture, composition patterns, and separation of concerns. Expert in identifying extractable logic, creating testable custom hooks, and maintaining clean component boundaries.
+
+## Known Error Patterns
+
+### 1. God Component (Too Much Logic)
+- **symptoms**:
+  - Component file exceeds 300 lines
+  - Multiple unrelated `useState`/`useEffect` pairs in one component
+  - Difficult to test individual behaviors
+  - Multiple concerns mixed (data fetching, form handling, animations)
+  - Code duplication across components for similar logic
+- **causes**:
+  - Organic growth without refactoring
+  - All logic added directly to the component instead of hooks
+  - No separation between presentation and business logic
+- **strategy**:
+  1. Identify logical groups: state + effects that belong together
+  2. Extract each group into a named custom hook: `useFormValidation`, `useDataFetch`
+  3. Component becomes a thin shell: hooks + JSX
+  4. Each hook should have a single responsibility
+  5. Hooks can compose other hooks
+- **tools**: file_read, file_edit, grep
+- **pitfalls**:
+  - Do NOT extract a hook with 10+ return values -- split further
+  - Do NOT create `useComponent` hooks that mirror the component 1:1 -- find meaningful abstractions
+  - Hooks should be reusable, not just "code moved to another file"
+
+### 2. Duplicated State Logic
+- **symptoms**:
+  - Same `useState` + `useEffect` pattern repeated in 3+ components
+  - Copy-paste of fetch/loading/error state management
+  - Identical form validation logic in multiple forms
+  - Similar timer/interval patterns across components
+- **causes**:
+  - No shared hook library in the project
+  - Developers unaware of existing hooks
+  - Similar but slightly different requirements leading to copy-paste
+- **strategy**:
+  1. Grep for repeated patterns: `useState.*loading`, `useEffect.*fetch`
+  2. Create a generalized hook with configuration parameters
+  3. Use TypeScript generics for type-safe data hooks
+  4. Document the hook's API and add it to a shared hooks directory
+  5. Replace all duplicated instances with the new hook
+- **tools**: grep, file_read, file_edit
+- **pitfalls**:
+  - Do NOT over-generalize -- if two patterns share 60% but differ in critical ways, two separate hooks may be better
+  - Ensure the extracted hook handles all edge cases from every call site
+
+### 3. Tightly Coupled Effects
+- **symptoms**:
+  - One `useEffect` does multiple unrelated things
+  - Dependency array contains unrelated values
+  - Changing one behavior requires modifying an unrelated effect
+  - Difficult to reason about when effects run
+- **causes**:
+  - Multiple concerns combined in one effect for convenience
+  - "Just add it to the existing effect" mentality
+  - Unclear mental model of effect lifecycle
+- **strategy**:
+  1. Split into separate `useEffect` calls -- one per concern
+  2. Group related state and effect into a custom hook
+  3. Each effect should have a clear, single purpose
+  4. Name the extracted hook after its purpose, not its implementation
+- **tools**: file_read, file_edit
+- **pitfalls**:
+  - Multiple effects are fine -- React handles them well
+  - Do NOT merge unrelated effects just to "reduce hook calls"
+  - Watch for effects that depend on each other -- these might need `useReducer` instead
+
+### 4. Untestable Component Logic
+- **symptoms**:
+  - Testing requires full component render for logic-only assertions
+  - Mocking is excessive because logic is interleaved with rendering
+  - Cannot test edge cases without UI interaction
+  - Business logic cannot be reused in different UI contexts
+- **causes**:
+  - Business logic lives inside the component body
+  - Data transformations done inline in JSX
+  - Side effects triggered by rendering, not by explicit calls
+- **strategy**:
+  1. Extract logic into a custom hook
+  2. Test the hook with `renderHook` from `@testing-library/react`
+  3. Hook returns a clean API: `{ data, loading, error, actions }`
+  4. Component becomes a thin rendering layer -- easy to test separately
+  5. Hook can be reused in different UI contexts (mobile, desktop, CLI)
+- **tools**: file_read, file_edit, shell_exec
+- **pitfalls**:
+  - `renderHook` is the correct way to test hooks -- do NOT call hooks outside React
+  - If a hook needs complex setup, consider if it is doing too much
+
+### 5. Hook Composition Failure
+- **symptoms**:
+  - Custom hook re-implements logic that exists in another hook
+  - Deep hook call chains that are hard to debug
+  - Hooks with too many parameters (> 4)
+  - Return type is a large tuple or object with 8+ fields
+- **causes**:
+  - Not composing existing hooks
+  - Trying to make one hook do everything
+  - Flat hook architecture instead of layered
+- **strategy**:
+  1. Build hooks in layers: primitive hooks -> domain hooks -> feature hooks
+  2. Primitive: `useLocalStorage`, `useDebounce`, `useMediaQuery`
+  3. Domain: `useAuth` (uses `useLocalStorage`), `useApi` (uses `useDebounce`)
+  4. Feature: `useUserSearch` (uses `useAuth` + `useApi` + `useDebounce`)
+  5. Each layer adds specific domain knowledge
+- **tools**: file_read, grep, file_edit
+- **pitfalls**:
+  - Avoid circular hook dependencies
+  - Keep primitive hooks truly primitive -- no business logic
+  - Document the hook layer architecture for the team
+
+## Extraction Rules
+
+### When to Extract
+- Same logic appears in 2+ components
+- Component has 3+ `useState` calls for unrelated concerns
+- Component file exceeds 200 lines of logic (excluding JSX)
+- An `useEffect` has 4+ dependencies from different concerns
+- You need to test business logic independently from rendering
+
+### When NOT to Extract
+- Logic is used in exactly one component and is simple (< 20 lines)
+- Extraction would create a hook with only one `useState` and no effects
+- The "hook" would just be a wrapper around a single function call
+- Logic is purely presentational (use a utility function instead)
+
+### Naming Conventions
+- `use<Resource><Action>`: `useUserFetch`, `useFormValidation`
+- NOT `use<Component>Logic`: avoid `useHeaderLogic`, `useSidebarStuff`
+- Return object, not tuple, if > 2 values: `{ data, loading, error, refetch }`
+- File name matches hook name: `useUserFetch.ts`
+
+### State + Effect Grouping
+Group these together in one hook:
+1. Related `useState` calls (e.g., `data`, `loading`, `error`)
+2. The `useEffect` that manages them (e.g., fetch call)
+3. Derived state (`useMemo`) from those states
+4. Event handlers (`useCallback`) that modify those states
+
+### Hook Composition Pattern
+```
+// Layer 1: Primitive
+function useDebounce<T>(value: T, delay: number): T { ... }
+
+// Layer 2: Domain
+function useSearchApi(query: string) {
+  const debouncedQuery = useDebounce(query, 300);
+  const [results, setResults] = useState([]);
+  useEffect(() => { /* fetch with debouncedQuery */ }, [debouncedQuery]);
+  return { results };
+}
+
+// Layer 3: Feature
+function useUserSearch() {
+  const [query, setQuery] = useState('');
+  const { results } = useSearchApi(query);
+  const filtered = useMemo(() => filterActive(results), [results]);
+  return { query, setQuery, results: filtered };
+}
+```
+
+### Testing Custom Hooks
+```
+import { renderHook, act } from '@testing-library/react';
+import { useCounter } from './useCounter';
+
+test('should increment counter', () => {
+  const { result } = renderHook(() => useCounter(0));
+  act(() => { result.current.increment(); });
+  expect(result.current.count).toBe(1);
+});
+
+test('should handle async operations', async () => {
+  const { result } = renderHook(() => useDataFetch('/api/users'));
+  expect(result.current.loading).toBe(true);
+  await waitFor(() => expect(result.current.loading).toBe(false));
+  expect(result.current.data).toBeDefined();
+});
+```
+
+## Tool Sequence
+1. **file_read** -- Read the target component to identify extractable logic groups
+2. **grep** -- Search for similar patterns across the codebase to identify reuse opportunities
+3. **grep** -- Check for existing hooks in `hooks/` or `utils/` that could be composed
+4. **file_edit** -- Create the new custom hook file with full TypeScript types
+5. **file_edit** -- Refactor the component to use the extracted hook
+6. **file_edit** -- Create test file for the hook using `renderHook`
+7. **shell_exec** -- Run `tsc --noEmit` to verify types
+8. **shell_exec** -- Run tests to verify behavior is preserved
+
+## Validation Checklist
+- [ ] Hook has a single, clear responsibility
+- [ ] Hook name follows `use<Resource><Action>` convention
+- [ ] Return type is a typed object (not a large tuple)
+- [ ] Hook is exported and documented with JSDoc
+- [ ] Component is simpler after extraction (fewer lines, fewer concerns)
+- [ ] All existing behavior is preserved (no regression)
+- [ ] Hook test file exists with `renderHook` tests
+- [ ] `tsc --noEmit` passes
+- [ ] `pnpm build` passes
+- [ ] No duplicated logic remains in the original component