fecode-cli 1.1.3 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/README.md +92 -8
  2. package/dist/index.js +23293 -1
  3. package/dist/{node.browser-BsGbhAIw.js → node.browser-2EgZAKSy.js} +1 -1
  4. package/dist/{node.browser-B5CfqNxN.js → node.browser-B5Gur0wd.js} +1 -1
  5. package/dist/{node.browser-BWLpZywP.js → node.browser-BSlAsiSV.js} +1 -1
  6. package/dist/{node.browser-7pW7d9_e.js → node.browser-CdVAMgSg.js} +1 -1
  7. package/dist/{src-CxriUNOE.js → src-CSWdjU4j.js} +4836 -4522
  8. package/dist/{src-DBoGZaxi.js → src-DY3OmBmT.js} +6670 -4557
  9. package/dist/{src-B_Z8CdqT.js → src-DcYf8vsK.js} +4850 -4526
  10. package/dist/{src-Bhec3XmL.js → src-DkWmcv2Q.js} +6677 -4604
  11. package/package.json +5 -2
  12. package/skills/accessibility/SKILL.md +98 -98
  13. package/skills/css/SKILL.md +90 -90
  14. package/skills/frontend-debugging/SKILL.md +201 -201
  15. package/skills/frontend-design/SKILL.md +358 -358
  16. package/skills/frontend-performance/SKILL.md +89 -89
  17. package/skills/frontend-testing/SKILL.md +87 -87
  18. package/skills/nextjs/SKILL.md +75 -75
  19. package/skills/react/SKILL.md +213 -213
  20. package/skills/responsive-design/SKILL.md +190 -190
  21. package/skills/svelte/SKILL.md +86 -86
  22. package/skills/tailwind/SKILL.md +74 -74
  23. package/skills/ui-review/SKILL.md +245 -245
  24. package/skills/vue/SKILL.md +72 -72
  25. package/dist/App.d.ts +0 -33
  26. package/dist/App.js +0 -2224
  27. package/dist/approvalResolver.d.ts +0 -12
  28. package/dist/approvalResolver.js +0 -112
  29. package/dist/commands.d.ts +0 -11
  30. package/dist/commands.js +0 -33
  31. package/dist/error-qAR8Lv-R.js +0 -57
  32. package/dist/index.d.ts +0 -3
  33. package/dist/node.browser-C9Wg-Fje.js +0 -46
  34. package/dist/node.browser-CADgAblr.js +0 -46
  35. package/dist/node.browser-Cse19Rko.js +0 -47
  36. package/dist/node.browser-Cx8sZi1Z.js +0 -46
  37. package/dist/node.browser-DtPNhPGQ.js +0 -46
  38. package/dist/node.browser-DvjMZMaq.js +0 -46
  39. package/dist/node.browser-EewJmuUw.js +0 -46
  40. package/dist/node.browser-J7voHtuR.js +0 -10
  41. package/dist/src-4fKRO0jn.js +0 -31655
  42. package/dist/src-8kA-5Kbs.js +0 -31591
  43. package/dist/src-C8Oe06wn.js +0 -31580
  44. package/dist/src-D78uLcuc.js +0 -31573
  45. package/dist/src-EyWDnffN.js +0 -31636
  46. package/dist/src-dhvwrHAJ.js +0 -31590
  47. package/dist/ui/AppShell.d.ts +0 -14
  48. package/dist/ui/AppShell.js +0 -25
  49. package/dist/ui/ApprovalPrompt.d.ts +0 -31
  50. package/dist/ui/ApprovalPrompt.js +0 -55
  51. package/dist/ui/BlockedView.d.ts +0 -13
  52. package/dist/ui/BlockedView.js +0 -7
  53. package/dist/ui/CommandPalette.d.ts +0 -8
  54. package/dist/ui/CommandPalette.js +0 -18
  55. package/dist/ui/CurrentStepView.d.ts +0 -16
  56. package/dist/ui/CurrentStepView.js +0 -28
  57. package/dist/ui/DiagnosticsView.d.ts +0 -45
  58. package/dist/ui/DiagnosticsView.js +0 -23
  59. package/dist/ui/ExecutionTimeline.d.ts +0 -15
  60. package/dist/ui/ExecutionTimeline.js +0 -51
  61. package/dist/ui/ExecutionView.d.ts +0 -42
  62. package/dist/ui/ExecutionView.js +0 -20
  63. package/dist/ui/Header.d.ts +0 -15
  64. package/dist/ui/Header.js +0 -47
  65. package/dist/ui/HelpView.d.ts +0 -3
  66. package/dist/ui/HelpView.js +0 -35
  67. package/dist/ui/MessageBubble.d.ts +0 -9
  68. package/dist/ui/MessageBubble.js +0 -58
  69. package/dist/ui/PlanStep.d.ts +0 -16
  70. package/dist/ui/PlanStep.js +0 -71
  71. package/dist/ui/PlanView.d.ts +0 -26
  72. package/dist/ui/PlanView.js +0 -24
  73. package/dist/ui/ProgressBar.d.ts +0 -10
  74. package/dist/ui/ProgressBar.js +0 -14
  75. package/dist/ui/RecoveryView.d.ts +0 -20
  76. package/dist/ui/RecoveryView.js +0 -19
  77. package/dist/ui/ReplanView.d.ts +0 -16
  78. package/dist/ui/ReplanView.js +0 -21
  79. package/dist/ui/ResumeView.d.ts +0 -15
  80. package/dist/ui/ResumeView.js +0 -25
  81. package/dist/ui/RiskNotice.d.ts +0 -10
  82. package/dist/ui/RiskNotice.js +0 -21
  83. package/dist/ui/RunHistoryView.d.ts +0 -15
  84. package/dist/ui/RunHistoryView.js +0 -39
  85. package/dist/ui/StatusBar.d.ts +0 -16
  86. package/dist/ui/StatusBar.js +0 -104
  87. package/dist/ui/TaskInput.d.ts +0 -15
  88. package/dist/ui/TaskInput.js +0 -8
  89. package/dist/ui/ThinkingBlock.d.ts +0 -8
  90. package/dist/ui/ThinkingBlock.js +0 -13
  91. package/dist/ui/ThinkingIndicator.d.ts +0 -7
  92. package/dist/ui/ThinkingIndicator.js +0 -20
  93. package/dist/ui/TurnView.d.ts +0 -13
  94. package/dist/ui/TurnView.js +0 -11
  95. package/dist/ui/WorkspaceStatus.d.ts +0 -20
  96. package/dist/ui/WorkspaceStatus.js +0 -23
  97. package/dist/ui/index.d.ts +0 -26
  98. package/dist/ui/index.js +0 -26
@@ -1,213 +1,213 @@
1
- ---
2
- name: react
3
- description: React component architecture, state management, effect guidelines, and rendering behavior.
4
- category: framework
5
- version: 2.1.0
6
- ---
7
-
8
- ## When to use
9
-
10
- - writing React components
11
- - managing React state
12
- - authoring custom hooks
13
- - React application
14
- - JSX/TSX React work
15
-
16
- ## When not to use
17
-
18
- - non-React frontend work
19
-
20
- ## Instructions
21
-
22
- ### Project Detection & Existing Rules
23
- - **Inspect package.json**: Identify the React version (e.g. 17 vs 18 vs 19).
24
- - **Inspect established conventions**: Check how the project handles state, side effects, and composition.
25
- - **Follow existing patterns**: Do not impose a new architecture (like switching state management libraries) simply because it is preferred, unless explicitly requested.
26
-
27
- ### Core Mental Model
28
- - **Components**: UI rendering units receiving inputs (props) and returning UI.
29
- - **Props**: Immutable inputs from parents.
30
- - **State**: Owned mutable UI state; changing it triggers re-renders.
31
- - **Derived Values**: Variables calculated from props or state during render. They are not state themselves.
32
- - **One-way Data Flow**: Data flows down, actions flow up.
33
-
34
- ### Common Failure Modes
35
- - **Stale Closure**:
36
- - *What it looks like*: A function (like inside an effect or timeout) uses an old value of state or props, rather than the latest.
37
- - *Common cause*: Missing or incorrect dependency arrays in hooks (`useEffect`, `useCallback`).
38
- - *What to inspect*: The dependency array of the hook and the variables referenced inside the closure.
39
- - *Appropriate fix*: Add missing dependencies, use the functional state updater (e.g., `setCount(c => c + 1)`), or use `useRef` for values that shouldn't trigger renders but need to be fresh.
40
- - **Infinite Effect Loop**:
41
- - *What it looks like*: The browser hangs or the console floods with re-render warnings.
42
- - *Common cause*: Unstable dependencies (e.g., creating a new object/array/function on every render and passing it to a dependency array) or state updates inside effects that re-trigger the same effect.
43
- - *What to inspect*: The dependency array and state setters inside the effect.
44
- - *Appropriate fix*: Stabilize dependencies with `useMemo`/`useCallback`, move logic inside the effect, or determine whether the effect should exist at all (often it can be derived during render).
45
- - **State Out of Sync**:
46
- - *What it looks like*: Updating one piece of state doesn't update related UI.
47
- - *Common cause*: Duplicated state (e.g., passing a prop and storing it in state) or derived state stored separately.
48
- - *What to inspect*: Multiple competing sources of truth.
49
- - *Appropriate fix*: Lift state up or compute the derived value directly during render.
50
- - **Incorrect Keys**:
51
- - *What it looks like*: List items re-render completely, input focus is lost, or the wrong item is deleted.
52
- - *Common cause*: Using array indexes as keys when list ordering or identity changes (e.g., filtering, sorting, or prepending items).
53
- - *What to inspect*: The `key` prop on mapped list elements.
54
- - *Appropriate fix*: Use a unique, stable identifier (like a database ID) for the `key`. Array indexes are only acceptable if the list is completely static and never changes order or size.
55
- - **Hydration / Server Rendering Problems**:
56
- - *What it looks like*: Console warnings about text content not matching between server and client, or broken styling on load. (Only relevant when the project uses SSR/server rendering like Next.js or Remix).
57
- - *Common cause*: Using browser-only values (like `window.innerWidth` or `localStorage`) during the initial render.
58
- - *Appropriate fix*: Wait until the component mounts (inside `useEffect`) to read browser-only values, or conditionally render the client-specific UI.
59
-
60
- ## Rules
61
-
62
- ### State
63
- Before adding state, determine:
64
- - Is the value independently mutable?
65
- - Can it be derived from existing props/state?
66
- - Who owns the value?
67
- - Does another component need it?
68
- Prefer derived values when possible. Avoid duplicated sources of truth.
69
- *Why*: Deriving values guarantees they are always in sync with the source of truth, eliminating entire classes of synchronization bugs.
70
-
71
- ### Effects
72
- Before adding `useEffect`, determine:
73
- - Is React synchronizing with an external system?
74
- - Could this logic happen during render?
75
- - Could this logic happen inside an event handler?
76
- - Is this actually derived state?
77
- Prefer avoiding an effect when no external synchronization is required.
78
- *Good*: subscriptions, timers, DOM synchronization, external APIs where appropriate.
79
- *Bad*: deriving one state value from another, transforming props into state unnecessarily, responding to a button click that belongs in an event handler.
80
-
81
- ### Component Extraction
82
- Before extracting a component, determine:
83
- - Does it have a clear responsibility?
84
- - Does extraction improve readability?
85
- - Is the component actually reusable?
86
- - Does extraction clarify state ownership?
87
- Do not extract every small JSX fragment. Only extract when it serves a structural, reuse, or performance purpose.
88
-
89
- ### Custom Hooks
90
- Before creating a custom hook, determine whether:
91
- - stateful behavior is reused
92
- - effect/subscription logic is reused
93
- - a meaningful behavioral abstraction exists
94
- Do not create hooks merely to move code into another file.
95
-
96
- ### Context
97
- Before introducing Context, determine:
98
- - Is the value genuinely shared across a subtree?
99
- - Would composition (passing components as props/children) solve the problem?
100
- - Is the value application-wide or merely needed by nearby components?
101
- Do not use Context as a default replacement for props.
102
- Do not introduce a state-management library unless requested or already used.
103
-
104
- ### Memoization
105
- Before using `useMemo`, `useCallback`, or `React.memo`, determine whether there is an actual performance problem.
106
- Prefer simple code unless profiling or a clear rendering-cost problem justifies memoization. Memoization has its own complexity, costs memory, and is not automatically an optimization.
107
-
108
- ### Controlled vs Uncontrolled Inputs
109
- Controlled when:
110
- - UI state must immediately drive application state
111
- - validation depends on current value
112
- - other UI reacts to the value
113
- Uncontrolled when:
114
- - the form is simple
115
- - DOM ownership is sufficient
116
- - continuous React state updates are unnecessary
117
- Do not prescribe one universally.
118
-
119
- ### Server State vs UI State
120
- Make the distinction clear:
121
- - *UI state*: modal open/closed, selected tab, input value.
122
- - *Server state*: API data, remote resources, cacheable backend data.
123
- Do not treat server data as ordinary local component state when the project already has an established server-state/data-fetching solution (like React Query, SWR, Apollo, or framework-specific routers). Do not introduce a new library.
124
-
125
- ## Workflow
126
-
127
- 1. **Inspect package.json and React version**: Understand what APIs are available.
128
- 2. **Inspect nearby components**: Understand the context of the files you are modifying.
129
- 3. **Identify existing state/data-fetching conventions**: Respect the established architecture.
130
- 4. **Identify ownership of the state being changed**: Ensure you modify the state at the correct level of the component tree.
131
- 5. **Determine whether the change needs state, derived values, effects, context, or a custom hook**: Apply the decision rules before writing code.
132
- 6. **Make the smallest change consistent with existing architecture**: Do not blindly rewrite surrounding code or impose new patterns.
133
- 7. **Check loading, error, empty, and interaction states**: Ensure the UI handles edge cases gracefully where relevant.
134
- 8. **Run the project's appropriate verification commands**: Verify the changes using the project's actual lint, typecheck, and test scripts.
135
-
136
- ## Anti-Patterns
137
-
138
- - **Unnecessary useEffect**
139
- - *What*: Using an effect to update a state variable based on a change in another state variable or prop.
140
- - *Why*: It causes unnecessary extra renders (cascading renders) and makes data flow harder to trace.
141
- - *Instead*: Compute the value directly during render.
142
- - **Duplicated derived state**
143
- - *What*: Copying a prop into local state to format it or modify it slightly.
144
- - *Why*: The local state becomes disconnected from the prop. If the parent updates the prop, the local state won't automatically update without complicated effect synchronization.
145
- - *Instead*: Derive the formatted value during render.
146
- - **Premature memoization**
147
- - *What*: Wrapping every function in `useCallback` and every variable in `useMemo` by default.
148
- - *Why*: It harms code readability, increases memory overhead, and often provides zero performance benefit unless passed to a heavily re-rendered or explicitly memoized child component.
149
- - *Instead*: Write simple code first. Optimize only when a performance issue is observed.
150
- - **Giant components**
151
- - *What*: Placing hundreds of lines of JSX and complex state logic into a single monolithic component.
152
- - *Why*: It creates a maintenance nightmare, mixes concerns, and causes the entire tree to re-render for minor local state changes.
153
- - *Instead*: Extract focused child components with clear responsibilities.
154
- - **Unnecessary context**
155
- - *What*: Putting a value into a React Context provider just to avoid passing it down one or two levels.
156
- - *Why*: Context couples components to the provider, making them harder to reuse, and causes all consumers to re-render when the context value changes.
157
- - *Instead*: Use prop drilling for shallow trees, or component composition (passing JSX as `children`).
158
- - **Unnecessary abstraction**
159
- - *What*: Creating highly generic, prop-heavy "smart" components (like a `BaseButton` that takes 30 props) instead of keeping things simple.
160
- - *Why*: The abstraction becomes too rigid and hard to understand.
161
- - *Instead*: Prefer simple, composable components over complex configurations.
162
- - **Direct mutation**
163
- - *What*: Writing `state.user.name = "Alice"` instead of using a setter function.
164
- - *Why*: React relies on object identity (reference equality) to trigger re-renders. Direct mutation silently changes the object but skips the render.
165
- - *Instead*: Always create new objects/arrays when updating state (`setUser({ ...user, name: "Alice" })`).
166
- - **Changing architecture without inspecting the project**
167
- - *What*: Installing a state management library like Zustand or Redux into a project that successfully uses React Context.
168
- - *Why*: It fragments the codebase and creates inconsistencies.
169
- - *Instead*: Adapt to the existing patterns unless explicitly requested to migrate.
170
-
171
- ## Examples
172
-
173
- ### Derived Value
174
-
175
- Bad:
176
- ```tsx
177
- const [fullName, setFullName] = useState("");
178
-
179
- useEffect(() => {
180
- setFullName(`${firstName} ${lastName}`);
181
- }, [firstName, lastName]);
182
- ```
183
-
184
- Better:
185
- ```tsx
186
- const fullName = `${firstName} ${lastName}`;
187
- ```
188
-
189
- ### Event Handler vs Effect
190
-
191
- Bad:
192
- ```tsx
193
- const [isSubmitting, setIsSubmitting] = useState(false);
194
-
195
- useEffect(() => {
196
- if (isSubmitting) {
197
- postData().then(() => setIsSubmitting(false));
198
- }
199
- }, [isSubmitting]);
200
-
201
- const handleClick = () => setIsSubmitting(true);
202
- ```
203
-
204
- Better:
205
- ```tsx
206
- const [isSubmitting, setIsSubmitting] = useState(false);
207
-
208
- const handleClick = async () => {
209
- setIsSubmitting(true);
210
- await postData();
211
- setIsSubmitting(false);
212
- };
213
- ```
1
+ ---
2
+ name: react
3
+ description: React component architecture, state management, effect guidelines, and rendering behavior.
4
+ category: framework
5
+ version: 2.1.0
6
+ ---
7
+
8
+ ## When to use
9
+
10
+ - writing React components
11
+ - managing React state
12
+ - authoring custom hooks
13
+ - React application
14
+ - JSX/TSX React work
15
+
16
+ ## When not to use
17
+
18
+ - non-React frontend work
19
+
20
+ ## Instructions
21
+
22
+ ### Project Detection & Existing Rules
23
+ - **Inspect package.json**: Identify the React version (e.g. 17 vs 18 vs 19).
24
+ - **Inspect established conventions**: Check how the project handles state, side effects, and composition.
25
+ - **Follow existing patterns**: Do not impose a new architecture (like switching state management libraries) simply because it is preferred, unless explicitly requested.
26
+
27
+ ### Core Mental Model
28
+ - **Components**: UI rendering units receiving inputs (props) and returning UI.
29
+ - **Props**: Immutable inputs from parents.
30
+ - **State**: Owned mutable UI state; changing it triggers re-renders.
31
+ - **Derived Values**: Variables calculated from props or state during render. They are not state themselves.
32
+ - **One-way Data Flow**: Data flows down, actions flow up.
33
+
34
+ ### Common Failure Modes
35
+ - **Stale Closure**:
36
+ - *What it looks like*: A function (like inside an effect or timeout) uses an old value of state or props, rather than the latest.
37
+ - *Common cause*: Missing or incorrect dependency arrays in hooks (`useEffect`, `useCallback`).
38
+ - *What to inspect*: The dependency array of the hook and the variables referenced inside the closure.
39
+ - *Appropriate fix*: Add missing dependencies, use the functional state updater (e.g., `setCount(c => c + 1)`), or use `useRef` for values that shouldn't trigger renders but need to be fresh.
40
+ - **Infinite Effect Loop**:
41
+ - *What it looks like*: The browser hangs or the console floods with re-render warnings.
42
+ - *Common cause*: Unstable dependencies (e.g., creating a new object/array/function on every render and passing it to a dependency array) or state updates inside effects that re-trigger the same effect.
43
+ - *What to inspect*: The dependency array and state setters inside the effect.
44
+ - *Appropriate fix*: Stabilize dependencies with `useMemo`/`useCallback`, move logic inside the effect, or determine whether the effect should exist at all (often it can be derived during render).
45
+ - **State Out of Sync**:
46
+ - *What it looks like*: Updating one piece of state doesn't update related UI.
47
+ - *Common cause*: Duplicated state (e.g., passing a prop and storing it in state) or derived state stored separately.
48
+ - *What to inspect*: Multiple competing sources of truth.
49
+ - *Appropriate fix*: Lift state up or compute the derived value directly during render.
50
+ - **Incorrect Keys**:
51
+ - *What it looks like*: List items re-render completely, input focus is lost, or the wrong item is deleted.
52
+ - *Common cause*: Using array indexes as keys when list ordering or identity changes (e.g., filtering, sorting, or prepending items).
53
+ - *What to inspect*: The `key` prop on mapped list elements.
54
+ - *Appropriate fix*: Use a unique, stable identifier (like a database ID) for the `key`. Array indexes are only acceptable if the list is completely static and never changes order or size.
55
+ - **Hydration / Server Rendering Problems**:
56
+ - *What it looks like*: Console warnings about text content not matching between server and client, or broken styling on load. (Only relevant when the project uses SSR/server rendering like Next.js or Remix).
57
+ - *Common cause*: Using browser-only values (like `window.innerWidth` or `localStorage`) during the initial render.
58
+ - *Appropriate fix*: Wait until the component mounts (inside `useEffect`) to read browser-only values, or conditionally render the client-specific UI.
59
+
60
+ ## Rules
61
+
62
+ ### State
63
+ Before adding state, determine:
64
+ - Is the value independently mutable?
65
+ - Can it be derived from existing props/state?
66
+ - Who owns the value?
67
+ - Does another component need it?
68
+ Prefer derived values when possible. Avoid duplicated sources of truth.
69
+ *Why*: Deriving values guarantees they are always in sync with the source of truth, eliminating entire classes of synchronization bugs.
70
+
71
+ ### Effects
72
+ Before adding `useEffect`, determine:
73
+ - Is React synchronizing with an external system?
74
+ - Could this logic happen during render?
75
+ - Could this logic happen inside an event handler?
76
+ - Is this actually derived state?
77
+ Prefer avoiding an effect when no external synchronization is required.
78
+ *Good*: subscriptions, timers, DOM synchronization, external APIs where appropriate.
79
+ *Bad*: deriving one state value from another, transforming props into state unnecessarily, responding to a button click that belongs in an event handler.
80
+
81
+ ### Component Extraction
82
+ Before extracting a component, determine:
83
+ - Does it have a clear responsibility?
84
+ - Does extraction improve readability?
85
+ - Is the component actually reusable?
86
+ - Does extraction clarify state ownership?
87
+ Do not extract every small JSX fragment. Only extract when it serves a structural, reuse, or performance purpose.
88
+
89
+ ### Custom Hooks
90
+ Before creating a custom hook, determine whether:
91
+ - stateful behavior is reused
92
+ - effect/subscription logic is reused
93
+ - a meaningful behavioral abstraction exists
94
+ Do not create hooks merely to move code into another file.
95
+
96
+ ### Context
97
+ Before introducing Context, determine:
98
+ - Is the value genuinely shared across a subtree?
99
+ - Would composition (passing components as props/children) solve the problem?
100
+ - Is the value application-wide or merely needed by nearby components?
101
+ Do not use Context as a default replacement for props.
102
+ Do not introduce a state-management library unless requested or already used.
103
+
104
+ ### Memoization
105
+ Before using `useMemo`, `useCallback`, or `React.memo`, determine whether there is an actual performance problem.
106
+ Prefer simple code unless profiling or a clear rendering-cost problem justifies memoization. Memoization has its own complexity, costs memory, and is not automatically an optimization.
107
+
108
+ ### Controlled vs Uncontrolled Inputs
109
+ Controlled when:
110
+ - UI state must immediately drive application state
111
+ - validation depends on current value
112
+ - other UI reacts to the value
113
+ Uncontrolled when:
114
+ - the form is simple
115
+ - DOM ownership is sufficient
116
+ - continuous React state updates are unnecessary
117
+ Do not prescribe one universally.
118
+
119
+ ### Server State vs UI State
120
+ Make the distinction clear:
121
+ - *UI state*: modal open/closed, selected tab, input value.
122
+ - *Server state*: API data, remote resources, cacheable backend data.
123
+ Do not treat server data as ordinary local component state when the project already has an established server-state/data-fetching solution (like React Query, SWR, Apollo, or framework-specific routers). Do not introduce a new library.
124
+
125
+ ## Workflow
126
+
127
+ 1. **Inspect package.json and React version**: Understand what APIs are available.
128
+ 2. **Inspect nearby components**: Understand the context of the files you are modifying.
129
+ 3. **Identify existing state/data-fetching conventions**: Respect the established architecture.
130
+ 4. **Identify ownership of the state being changed**: Ensure you modify the state at the correct level of the component tree.
131
+ 5. **Determine whether the change needs state, derived values, effects, context, or a custom hook**: Apply the decision rules before writing code.
132
+ 6. **Make the smallest change consistent with existing architecture**: Do not blindly rewrite surrounding code or impose new patterns.
133
+ 7. **Check loading, error, empty, and interaction states**: Ensure the UI handles edge cases gracefully where relevant.
134
+ 8. **Run the project's appropriate verification commands**: Verify the changes using the project's actual lint, typecheck, and test scripts.
135
+
136
+ ## Anti-Patterns
137
+
138
+ - **Unnecessary useEffect**
139
+ - *What*: Using an effect to update a state variable based on a change in another state variable or prop.
140
+ - *Why*: It causes unnecessary extra renders (cascading renders) and makes data flow harder to trace.
141
+ - *Instead*: Compute the value directly during render.
142
+ - **Duplicated derived state**
143
+ - *What*: Copying a prop into local state to format it or modify it slightly.
144
+ - *Why*: The local state becomes disconnected from the prop. If the parent updates the prop, the local state won't automatically update without complicated effect synchronization.
145
+ - *Instead*: Derive the formatted value during render.
146
+ - **Premature memoization**
147
+ - *What*: Wrapping every function in `useCallback` and every variable in `useMemo` by default.
148
+ - *Why*: It harms code readability, increases memory overhead, and often provides zero performance benefit unless passed to a heavily re-rendered or explicitly memoized child component.
149
+ - *Instead*: Write simple code first. Optimize only when a performance issue is observed.
150
+ - **Giant components**
151
+ - *What*: Placing hundreds of lines of JSX and complex state logic into a single monolithic component.
152
+ - *Why*: It creates a maintenance nightmare, mixes concerns, and causes the entire tree to re-render for minor local state changes.
153
+ - *Instead*: Extract focused child components with clear responsibilities.
154
+ - **Unnecessary context**
155
+ - *What*: Putting a value into a React Context provider just to avoid passing it down one or two levels.
156
+ - *Why*: Context couples components to the provider, making them harder to reuse, and causes all consumers to re-render when the context value changes.
157
+ - *Instead*: Use prop drilling for shallow trees, or component composition (passing JSX as `children`).
158
+ - **Unnecessary abstraction**
159
+ - *What*: Creating highly generic, prop-heavy "smart" components (like a `BaseButton` that takes 30 props) instead of keeping things simple.
160
+ - *Why*: The abstraction becomes too rigid and hard to understand.
161
+ - *Instead*: Prefer simple, composable components over complex configurations.
162
+ - **Direct mutation**
163
+ - *What*: Writing `state.user.name = "Alice"` instead of using a setter function.
164
+ - *Why*: React relies on object identity (reference equality) to trigger re-renders. Direct mutation silently changes the object but skips the render.
165
+ - *Instead*: Always create new objects/arrays when updating state (`setUser({ ...user, name: "Alice" })`).
166
+ - **Changing architecture without inspecting the project**
167
+ - *What*: Installing a state management library like Zustand or Redux into a project that successfully uses React Context.
168
+ - *Why*: It fragments the codebase and creates inconsistencies.
169
+ - *Instead*: Adapt to the existing patterns unless explicitly requested to migrate.
170
+
171
+ ## Examples
172
+
173
+ ### Derived Value
174
+
175
+ Bad:
176
+ ```tsx
177
+ const [fullName, setFullName] = useState("");
178
+
179
+ useEffect(() => {
180
+ setFullName(`${firstName} ${lastName}`);
181
+ }, [firstName, lastName]);
182
+ ```
183
+
184
+ Better:
185
+ ```tsx
186
+ const fullName = `${firstName} ${lastName}`;
187
+ ```
188
+
189
+ ### Event Handler vs Effect
190
+
191
+ Bad:
192
+ ```tsx
193
+ const [isSubmitting, setIsSubmitting] = useState(false);
194
+
195
+ useEffect(() => {
196
+ if (isSubmitting) {
197
+ postData().then(() => setIsSubmitting(false));
198
+ }
199
+ }, [isSubmitting]);
200
+
201
+ const handleClick = () => setIsSubmitting(true);
202
+ ```
203
+
204
+ Better:
205
+ ```tsx
206
+ const [isSubmitting, setIsSubmitting] = useState(false);
207
+
208
+ const handleClick = async () => {
209
+ setIsSubmitting(true);
210
+ await postData();
211
+ setIsSubmitting(false);
212
+ };
213
+ ```