fecode-cli 1.1.2 → 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.
- package/README.md +101 -10
- package/dist/error-D4a-8BXd.js +56 -0
- package/dist/index.js +9770 -4513
- package/dist/node.browser-2EgZAKSy.js +46 -0
- package/dist/node.browser-B5Gur0wd.js +46 -0
- package/dist/node.browser-BSlAsiSV.js +46 -0
- package/dist/node.browser-BraUi2yf.js +9 -0
- package/dist/node.browser-CdVAMgSg.js +46 -0
- package/dist/src-CSWdjU4j.js +31870 -0
- package/dist/src-DY3OmBmT.js +33646 -0
- package/dist/src-DcYf8vsK.js +31880 -0
- package/dist/src-DkWmcv2Q.js +33647 -0
- package/package.json +5 -2
- package/skills/accessibility/SKILL.md +98 -98
- package/skills/css/SKILL.md +90 -90
- package/skills/frontend-debugging/SKILL.md +201 -201
- package/skills/frontend-design/SKILL.md +358 -358
- package/skills/frontend-performance/SKILL.md +89 -89
- package/skills/frontend-testing/SKILL.md +87 -87
- package/skills/nextjs/SKILL.md +75 -75
- package/skills/react/SKILL.md +213 -213
- package/skills/responsive-design/SKILL.md +190 -190
- package/skills/svelte/SKILL.md +86 -86
- package/skills/tailwind/SKILL.md +74 -74
- package/skills/ui-review/SKILL.md +245 -245
- package/skills/vue/SKILL.md +72 -72
- package/dist/App.d.ts +0 -33
- package/dist/App.js +0 -2224
- package/dist/approvalResolver.d.ts +0 -12
- package/dist/approvalResolver.js +0 -112
- package/dist/commands.d.ts +0 -11
- package/dist/commands.js +0 -33
- package/dist/index.d.ts +0 -3
- package/dist/ui/AppShell.d.ts +0 -14
- package/dist/ui/AppShell.js +0 -25
- package/dist/ui/ApprovalPrompt.d.ts +0 -31
- package/dist/ui/ApprovalPrompt.js +0 -55
- package/dist/ui/BlockedView.d.ts +0 -13
- package/dist/ui/BlockedView.js +0 -7
- package/dist/ui/CommandPalette.d.ts +0 -8
- package/dist/ui/CommandPalette.js +0 -18
- package/dist/ui/CurrentStepView.d.ts +0 -16
- package/dist/ui/CurrentStepView.js +0 -28
- package/dist/ui/DiagnosticsView.d.ts +0 -45
- package/dist/ui/DiagnosticsView.js +0 -23
- package/dist/ui/ExecutionTimeline.d.ts +0 -15
- package/dist/ui/ExecutionTimeline.js +0 -51
- package/dist/ui/ExecutionView.d.ts +0 -42
- package/dist/ui/ExecutionView.js +0 -20
- package/dist/ui/Header.d.ts +0 -15
- package/dist/ui/Header.js +0 -47
- package/dist/ui/HelpView.d.ts +0 -3
- package/dist/ui/HelpView.js +0 -35
- package/dist/ui/MessageBubble.d.ts +0 -9
- package/dist/ui/MessageBubble.js +0 -58
- package/dist/ui/PlanStep.d.ts +0 -16
- package/dist/ui/PlanStep.js +0 -71
- package/dist/ui/PlanView.d.ts +0 -26
- package/dist/ui/PlanView.js +0 -24
- package/dist/ui/ProgressBar.d.ts +0 -10
- package/dist/ui/ProgressBar.js +0 -14
- package/dist/ui/RecoveryView.d.ts +0 -20
- package/dist/ui/RecoveryView.js +0 -19
- package/dist/ui/ReplanView.d.ts +0 -16
- package/dist/ui/ReplanView.js +0 -21
- package/dist/ui/ResumeView.d.ts +0 -15
- package/dist/ui/ResumeView.js +0 -25
- package/dist/ui/RiskNotice.d.ts +0 -10
- package/dist/ui/RiskNotice.js +0 -21
- package/dist/ui/RunHistoryView.d.ts +0 -15
- package/dist/ui/RunHistoryView.js +0 -39
- package/dist/ui/StatusBar.d.ts +0 -16
- package/dist/ui/StatusBar.js +0 -104
- package/dist/ui/TaskInput.d.ts +0 -15
- package/dist/ui/TaskInput.js +0 -8
- package/dist/ui/ThinkingBlock.d.ts +0 -8
- package/dist/ui/ThinkingBlock.js +0 -13
- package/dist/ui/ThinkingIndicator.d.ts +0 -7
- package/dist/ui/ThinkingIndicator.js +0 -20
- package/dist/ui/TurnView.d.ts +0 -13
- package/dist/ui/TurnView.js +0 -11
- package/dist/ui/WorkspaceStatus.d.ts +0 -20
- package/dist/ui/WorkspaceStatus.js +0 -23
- package/dist/ui/index.d.ts +0 -26
- package/dist/ui/index.js +0 -26
|
@@ -1,201 +1,201 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: frontend-debugging
|
|
3
|
-
description: Systematic frontend diagnosis and repair methodology. Apply when a UI component, layout, interaction, or state is broken or behaving unexpectedly. This skill teaches structured debugging — reproduce, inspect, isolate, hypothesize, minimal change, verify — rather than guessing and editing code that looks wrong.
|
|
4
|
-
category: frontend
|
|
5
|
-
version: 1.0.0
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
# Frontend Debugging
|
|
9
|
-
|
|
10
|
-
## When to use
|
|
11
|
-
- A UI component renders incorrectly or not at all
|
|
12
|
-
- A layout breaks at a specific viewport width or state
|
|
13
|
-
- An interactive element does not respond as expected
|
|
14
|
-
- A data display shows wrong, missing, or stale information
|
|
15
|
-
- A runtime error appears in the console
|
|
16
|
-
- A CSS or styling rule does not apply as expected
|
|
17
|
-
- A state transition produces unexpected UI behavior
|
|
18
|
-
|
|
19
|
-
## When not to use
|
|
20
|
-
- Purely backend API issues with no UI impact
|
|
21
|
-
- Writing new features from scratch (use frontend-design instead)
|
|
22
|
-
- Reviewing code quality without a specific failure (use ui-review instead)
|
|
23
|
-
|
|
24
|
-
## Instructions
|
|
25
|
-
- Do not edit code because something "looks wrong" — form a concrete diagnosis first.
|
|
26
|
-
- Use the existing FeCode tools (list_directory, read_file, search_files) to gather information before hypothesizing.
|
|
27
|
-
- Classify the problem type before attempting a fix: rendering, styling, state, data, event, or environment.
|
|
28
|
-
- Prefer the smallest possible change that fixes the actual root cause over refactoring the surrounding code.
|
|
29
|
-
- Verify the fix resolves the original symptom and does not introduce regressions.
|
|
30
|
-
- Never suppress or hide an error to make verification pass.
|
|
31
|
-
|
|
32
|
-
## Core Debugging Principle
|
|
33
|
-
|
|
34
|
-
Follow this sequence:
|
|
35
|
-
|
|
36
|
-
```
|
|
37
|
-
Symptom
|
|
38
|
-
→ Reproduce
|
|
39
|
-
→ Inspect
|
|
40
|
-
→ Isolate
|
|
41
|
-
→ Hypothesize
|
|
42
|
-
→ Minimal change
|
|
43
|
-
→ Verify
|
|
44
|
-
→ Re-check
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
Do not skip steps. Skipping reproduction and inspection leads to guessing, which leads to changes that mask symptoms rather than fix causes.
|
|
48
|
-
|
|
49
|
-
## Step 1: Understand the Symptom
|
|
50
|
-
|
|
51
|
-
Before touching any file:
|
|
52
|
-
- What exactly is broken? (visual glitch, wrong output, no output, crash, interaction failure)
|
|
53
|
-
- Where does it happen? (specific page, component, viewport, state, user action)
|
|
54
|
-
- When does it happen? (always, sometimes, specific condition, after a particular action)
|
|
55
|
-
- Is it consistent or intermittent?
|
|
56
|
-
- What is the expected behavior vs. the observed behavior?
|
|
57
|
-
|
|
58
|
-
Do not proceed until you can state the symptom precisely.
|
|
59
|
-
|
|
60
|
-
## Step 2: Reproduce or Establish the Failing Condition
|
|
61
|
-
|
|
62
|
-
If you cannot reproduce the problem, you cannot verify the fix.
|
|
63
|
-
|
|
64
|
-
- Identify the exact path through the application that triggers the failure
|
|
65
|
-
- Identify whether the failure depends on a specific viewport, data state, user action, or environment
|
|
66
|
-
- For intermittent failures, identify the conditions that increase the likelihood
|
|
67
|
-
|
|
68
|
-
If browser tools are available, inspect:
|
|
69
|
-
- Console errors and stack traces
|
|
70
|
-
- Network requests and failures
|
|
71
|
-
- DOM state at the moment of failure
|
|
72
|
-
- Applied CSS rules
|
|
73
|
-
|
|
74
|
-
Do not invent browser output when browser tools are unavailable. Work from code inspection instead.
|
|
75
|
-
|
|
76
|
-
## Step 3: Investigate the Repository
|
|
77
|
-
|
|
78
|
-
Use FeCode tools to gather information before forming a hypothesis:
|
|
79
|
-
|
|
80
|
-
```
|
|
81
|
-
list_directory — understand file structure
|
|
82
|
-
search_files — find component, class name, or error message
|
|
83
|
-
read_file — inspect the relevant component, styles, data source
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
Inspect in this order:
|
|
87
|
-
1. The component where the symptom appears
|
|
88
|
-
2. Its parent component (props, context, state passed down)
|
|
89
|
-
3. Associated styles or class names
|
|
90
|
-
4. Data source or API response shape
|
|
91
|
-
5. State management (local state, context, store)
|
|
92
|
-
6. Routing and navigation (if the issue is page-level)
|
|
93
|
-
7. Configuration (if the issue looks environmental)
|
|
94
|
-
|
|
95
|
-
Read the actual code — do not rely on assumptions about what it probably does.
|
|
96
|
-
|
|
97
|
-
## Step 4: Classify the Problem
|
|
98
|
-
|
|
99
|
-
Before hypothesizing a fix, identify what category the problem belongs to:
|
|
100
|
-
|
|
101
|
-
| Category | Indicators |
|
|
102
|
-
|----------|-----------|
|
|
103
|
-
| **Rendering** | Component not appearing, wrong element rendered, conditional rendering issue |
|
|
104
|
-
| **Styling/CSS** | Element appears but looks wrong — position, size, color, visibility |
|
|
105
|
-
| **State** | UI shows stale data, updates don't propagate, wrong value displayed |
|
|
106
|
-
| **Data** | Fetched data is wrong, missing, or in an unexpected shape |
|
|
107
|
-
| **Event/Interaction** | Handler not firing, wrong handler attached, event not propagating |
|
|
108
|
-
| **Environment** | Works locally but not in another environment; configuration or API key issue |
|
|
109
|
-
|
|
110
|
-
Solving the wrong category wastes time. A styling fix will not resolve a state problem.
|
|
111
|
-
|
|
112
|
-
## CSS and Layout Debugging
|
|
113
|
-
|
|
114
|
-
When a CSS issue is suspected, reason systematically through:
|
|
115
|
-
|
|
116
|
-
- **Box model**: `width`, `height`, `padding`, `border`, `margin`
|
|
117
|
-
- **Display**: `block`, `inline`, `flex`, `grid`, `inline-flex`, `none`
|
|
118
|
-
- **Position**: `static`, `relative`, `absolute`, `fixed`, `sticky`
|
|
119
|
-
- **Overflow**: `visible`, `hidden`, `scroll`, `auto` — and which ancestor creates the clipping context
|
|
120
|
-
- **Stacking contexts**: `z-index` only works within the same stacking context
|
|
121
|
-
- **Flex sizing**: `flex-grow`, `flex-shrink`, `flex-basis`, `min-width: 0`
|
|
122
|
-
- **Grid sizing**: explicit vs. implicit tracks, `fr` units, `minmax()`
|
|
123
|
-
- **Specificity**: which rule is actually winning, and why
|
|
124
|
-
- **Inheritance**: some properties inherit unexpectedly
|
|
125
|
-
|
|
126
|
-
**Common CSS traps:**
|
|
127
|
-
- `overflow: hidden` on a parent clips children with `position: sticky`
|
|
128
|
-
- `min-width` defaults on flex items prevent shrinking — add `min-width: 0`
|
|
129
|
-
- `z-index` on an element inside a stacking context with `z-index: 0` cannot escape it
|
|
130
|
-
- `height: 100%` requires an ancestor with an explicit height
|
|
131
|
-
|
|
132
|
-
## State and Data Debugging
|
|
133
|
-
|
|
134
|
-
- Confirm that the data source (API, store, prop, context) is actually returning what you expect
|
|
135
|
-
- Confirm that state updates trigger re-renders where needed
|
|
136
|
-
- Confirm that async operations (fetch, suspense, streaming) are completing before the component tries to render
|
|
137
|
-
- Distinguish between "data is wrong" and "data is correct but rendered incorrectly"
|
|
138
|
-
|
|
139
|
-
## Step 5: Form a Concrete Hypothesis
|
|
140
|
-
|
|
141
|
-
Before changing any file, state your hypothesis explicitly:
|
|
142
|
-
|
|
143
|
-
> "I believe the problem is X, caused by Y, and the fix is Z."
|
|
144
|
-
|
|
145
|
-
If you cannot form a specific hypothesis, gather more information rather than trying random edits.
|
|
146
|
-
|
|
147
|
-
## Step 6: Make the Minimal Change
|
|
148
|
-
|
|
149
|
-
- Fix the root cause, not the symptom
|
|
150
|
-
- Do not refactor the entire component to fix a single CSS property
|
|
151
|
-
- Do not add workaround overrides when the underlying issue can be fixed directly
|
|
152
|
-
- Do not restructure state management when the display logic is wrong
|
|
153
|
-
|
|
154
|
-
Prefer surgical edits. The more code you change, the more you risk introducing regressions.
|
|
155
|
-
|
|
156
|
-
## Step 7: Verify
|
|
157
|
-
|
|
158
|
-
After making the fix:
|
|
159
|
-
1. Re-read the changed code — does it actually address the root cause?
|
|
160
|
-
2. Run any relevant tests or build checks
|
|
161
|
-
3. Mentally or actually reproduce the original failing scenario
|
|
162
|
-
4. Check adjacent states: does fixing one state break another?
|
|
163
|
-
5. Check any related components that may share the affected code
|
|
164
|
-
|
|
165
|
-
## Debugging Workflow
|
|
166
|
-
|
|
167
|
-
1. Understand the symptom precisely.
|
|
168
|
-
2. Reproduce or establish the failing condition.
|
|
169
|
-
3. Use list_directory, search_files, and read_file to gather information.
|
|
170
|
-
4. Read the component, its parents, its styles, and its data source.
|
|
171
|
-
5. Classify the problem type.
|
|
172
|
-
6. Form a concrete hypothesis about the root cause.
|
|
173
|
-
7. Make the smallest appropriate change.
|
|
174
|
-
8. Verify: re-read, run checks, reproduce the original scenario.
|
|
175
|
-
9. Confirm the original failure is resolved.
|
|
176
|
-
10. Check for regressions in related states and components.
|
|
177
|
-
|
|
178
|
-
## Avoid
|
|
179
|
-
|
|
180
|
-
- Editing code because it "looks like" the problem without verifying through inspection.
|
|
181
|
-
- Changing multiple files simultaneously before understanding the issue — each change obscures what fixed what.
|
|
182
|
-
- Rewriting a component to fix a problem that was in a single property.
|
|
183
|
-
- Adding CSS overrides that mask the real issue rather than correcting it.
|
|
184
|
-
- Hiding errors with try/catch or null checks without addressing the underlying cause.
|
|
185
|
-
- Disabling TypeScript or lint checks to make verification pass — if they flag something, investigate it.
|
|
186
|
-
- Declaring success before reproducing the original scenario with the fix applied.
|
|
187
|
-
- Inventing browser console output when browser tools are unavailable.
|
|
188
|
-
|
|
189
|
-
## Examples
|
|
190
|
-
|
|
191
|
-
### Example: Diagnosing layout overflow before editing
|
|
192
|
-
|
|
193
|
-
Wrong approach: "The component looks too wide, I'll add `overflow: hidden` to the parent."
|
|
194
|
-
|
|
195
|
-
Correct approach: Identify which specific element is causing overflow. Check `min-width` on flex children (common culprit). Inspect the box model of the overflowing element. Fix the constraint that prevents correct shrinking, not the visibility of the overflow.
|
|
196
|
-
|
|
197
|
-
### Example: State vs. rendering classification
|
|
198
|
-
|
|
199
|
-
Symptom: "The user's name shows the old value after they update their profile."
|
|
200
|
-
|
|
201
|
-
Classify first: Is the API returning the old value? Is the store not updating? Is the component not re-rendering? Is it re-rendering but showing a stale closure value? Each of these has a different fix. Read the data flow before editing.
|
|
1
|
+
---
|
|
2
|
+
name: frontend-debugging
|
|
3
|
+
description: Systematic frontend diagnosis and repair methodology. Apply when a UI component, layout, interaction, or state is broken or behaving unexpectedly. This skill teaches structured debugging — reproduce, inspect, isolate, hypothesize, minimal change, verify — rather than guessing and editing code that looks wrong.
|
|
4
|
+
category: frontend
|
|
5
|
+
version: 1.0.0
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Frontend Debugging
|
|
9
|
+
|
|
10
|
+
## When to use
|
|
11
|
+
- A UI component renders incorrectly or not at all
|
|
12
|
+
- A layout breaks at a specific viewport width or state
|
|
13
|
+
- An interactive element does not respond as expected
|
|
14
|
+
- A data display shows wrong, missing, or stale information
|
|
15
|
+
- A runtime error appears in the console
|
|
16
|
+
- A CSS or styling rule does not apply as expected
|
|
17
|
+
- A state transition produces unexpected UI behavior
|
|
18
|
+
|
|
19
|
+
## When not to use
|
|
20
|
+
- Purely backend API issues with no UI impact
|
|
21
|
+
- Writing new features from scratch (use frontend-design instead)
|
|
22
|
+
- Reviewing code quality without a specific failure (use ui-review instead)
|
|
23
|
+
|
|
24
|
+
## Instructions
|
|
25
|
+
- Do not edit code because something "looks wrong" — form a concrete diagnosis first.
|
|
26
|
+
- Use the existing FeCode tools (list_directory, read_file, search_files) to gather information before hypothesizing.
|
|
27
|
+
- Classify the problem type before attempting a fix: rendering, styling, state, data, event, or environment.
|
|
28
|
+
- Prefer the smallest possible change that fixes the actual root cause over refactoring the surrounding code.
|
|
29
|
+
- Verify the fix resolves the original symptom and does not introduce regressions.
|
|
30
|
+
- Never suppress or hide an error to make verification pass.
|
|
31
|
+
|
|
32
|
+
## Core Debugging Principle
|
|
33
|
+
|
|
34
|
+
Follow this sequence:
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
Symptom
|
|
38
|
+
→ Reproduce
|
|
39
|
+
→ Inspect
|
|
40
|
+
→ Isolate
|
|
41
|
+
→ Hypothesize
|
|
42
|
+
→ Minimal change
|
|
43
|
+
→ Verify
|
|
44
|
+
→ Re-check
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Do not skip steps. Skipping reproduction and inspection leads to guessing, which leads to changes that mask symptoms rather than fix causes.
|
|
48
|
+
|
|
49
|
+
## Step 1: Understand the Symptom
|
|
50
|
+
|
|
51
|
+
Before touching any file:
|
|
52
|
+
- What exactly is broken? (visual glitch, wrong output, no output, crash, interaction failure)
|
|
53
|
+
- Where does it happen? (specific page, component, viewport, state, user action)
|
|
54
|
+
- When does it happen? (always, sometimes, specific condition, after a particular action)
|
|
55
|
+
- Is it consistent or intermittent?
|
|
56
|
+
- What is the expected behavior vs. the observed behavior?
|
|
57
|
+
|
|
58
|
+
Do not proceed until you can state the symptom precisely.
|
|
59
|
+
|
|
60
|
+
## Step 2: Reproduce or Establish the Failing Condition
|
|
61
|
+
|
|
62
|
+
If you cannot reproduce the problem, you cannot verify the fix.
|
|
63
|
+
|
|
64
|
+
- Identify the exact path through the application that triggers the failure
|
|
65
|
+
- Identify whether the failure depends on a specific viewport, data state, user action, or environment
|
|
66
|
+
- For intermittent failures, identify the conditions that increase the likelihood
|
|
67
|
+
|
|
68
|
+
If browser tools are available, inspect:
|
|
69
|
+
- Console errors and stack traces
|
|
70
|
+
- Network requests and failures
|
|
71
|
+
- DOM state at the moment of failure
|
|
72
|
+
- Applied CSS rules
|
|
73
|
+
|
|
74
|
+
Do not invent browser output when browser tools are unavailable. Work from code inspection instead.
|
|
75
|
+
|
|
76
|
+
## Step 3: Investigate the Repository
|
|
77
|
+
|
|
78
|
+
Use FeCode tools to gather information before forming a hypothesis:
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
list_directory — understand file structure
|
|
82
|
+
search_files — find component, class name, or error message
|
|
83
|
+
read_file — inspect the relevant component, styles, data source
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Inspect in this order:
|
|
87
|
+
1. The component where the symptom appears
|
|
88
|
+
2. Its parent component (props, context, state passed down)
|
|
89
|
+
3. Associated styles or class names
|
|
90
|
+
4. Data source or API response shape
|
|
91
|
+
5. State management (local state, context, store)
|
|
92
|
+
6. Routing and navigation (if the issue is page-level)
|
|
93
|
+
7. Configuration (if the issue looks environmental)
|
|
94
|
+
|
|
95
|
+
Read the actual code — do not rely on assumptions about what it probably does.
|
|
96
|
+
|
|
97
|
+
## Step 4: Classify the Problem
|
|
98
|
+
|
|
99
|
+
Before hypothesizing a fix, identify what category the problem belongs to:
|
|
100
|
+
|
|
101
|
+
| Category | Indicators |
|
|
102
|
+
|----------|-----------|
|
|
103
|
+
| **Rendering** | Component not appearing, wrong element rendered, conditional rendering issue |
|
|
104
|
+
| **Styling/CSS** | Element appears but looks wrong — position, size, color, visibility |
|
|
105
|
+
| **State** | UI shows stale data, updates don't propagate, wrong value displayed |
|
|
106
|
+
| **Data** | Fetched data is wrong, missing, or in an unexpected shape |
|
|
107
|
+
| **Event/Interaction** | Handler not firing, wrong handler attached, event not propagating |
|
|
108
|
+
| **Environment** | Works locally but not in another environment; configuration or API key issue |
|
|
109
|
+
|
|
110
|
+
Solving the wrong category wastes time. A styling fix will not resolve a state problem.
|
|
111
|
+
|
|
112
|
+
## CSS and Layout Debugging
|
|
113
|
+
|
|
114
|
+
When a CSS issue is suspected, reason systematically through:
|
|
115
|
+
|
|
116
|
+
- **Box model**: `width`, `height`, `padding`, `border`, `margin`
|
|
117
|
+
- **Display**: `block`, `inline`, `flex`, `grid`, `inline-flex`, `none`
|
|
118
|
+
- **Position**: `static`, `relative`, `absolute`, `fixed`, `sticky`
|
|
119
|
+
- **Overflow**: `visible`, `hidden`, `scroll`, `auto` — and which ancestor creates the clipping context
|
|
120
|
+
- **Stacking contexts**: `z-index` only works within the same stacking context
|
|
121
|
+
- **Flex sizing**: `flex-grow`, `flex-shrink`, `flex-basis`, `min-width: 0`
|
|
122
|
+
- **Grid sizing**: explicit vs. implicit tracks, `fr` units, `minmax()`
|
|
123
|
+
- **Specificity**: which rule is actually winning, and why
|
|
124
|
+
- **Inheritance**: some properties inherit unexpectedly
|
|
125
|
+
|
|
126
|
+
**Common CSS traps:**
|
|
127
|
+
- `overflow: hidden` on a parent clips children with `position: sticky`
|
|
128
|
+
- `min-width` defaults on flex items prevent shrinking — add `min-width: 0`
|
|
129
|
+
- `z-index` on an element inside a stacking context with `z-index: 0` cannot escape it
|
|
130
|
+
- `height: 100%` requires an ancestor with an explicit height
|
|
131
|
+
|
|
132
|
+
## State and Data Debugging
|
|
133
|
+
|
|
134
|
+
- Confirm that the data source (API, store, prop, context) is actually returning what you expect
|
|
135
|
+
- Confirm that state updates trigger re-renders where needed
|
|
136
|
+
- Confirm that async operations (fetch, suspense, streaming) are completing before the component tries to render
|
|
137
|
+
- Distinguish between "data is wrong" and "data is correct but rendered incorrectly"
|
|
138
|
+
|
|
139
|
+
## Step 5: Form a Concrete Hypothesis
|
|
140
|
+
|
|
141
|
+
Before changing any file, state your hypothesis explicitly:
|
|
142
|
+
|
|
143
|
+
> "I believe the problem is X, caused by Y, and the fix is Z."
|
|
144
|
+
|
|
145
|
+
If you cannot form a specific hypothesis, gather more information rather than trying random edits.
|
|
146
|
+
|
|
147
|
+
## Step 6: Make the Minimal Change
|
|
148
|
+
|
|
149
|
+
- Fix the root cause, not the symptom
|
|
150
|
+
- Do not refactor the entire component to fix a single CSS property
|
|
151
|
+
- Do not add workaround overrides when the underlying issue can be fixed directly
|
|
152
|
+
- Do not restructure state management when the display logic is wrong
|
|
153
|
+
|
|
154
|
+
Prefer surgical edits. The more code you change, the more you risk introducing regressions.
|
|
155
|
+
|
|
156
|
+
## Step 7: Verify
|
|
157
|
+
|
|
158
|
+
After making the fix:
|
|
159
|
+
1. Re-read the changed code — does it actually address the root cause?
|
|
160
|
+
2. Run any relevant tests or build checks
|
|
161
|
+
3. Mentally or actually reproduce the original failing scenario
|
|
162
|
+
4. Check adjacent states: does fixing one state break another?
|
|
163
|
+
5. Check any related components that may share the affected code
|
|
164
|
+
|
|
165
|
+
## Debugging Workflow
|
|
166
|
+
|
|
167
|
+
1. Understand the symptom precisely.
|
|
168
|
+
2. Reproduce or establish the failing condition.
|
|
169
|
+
3. Use list_directory, search_files, and read_file to gather information.
|
|
170
|
+
4. Read the component, its parents, its styles, and its data source.
|
|
171
|
+
5. Classify the problem type.
|
|
172
|
+
6. Form a concrete hypothesis about the root cause.
|
|
173
|
+
7. Make the smallest appropriate change.
|
|
174
|
+
8. Verify: re-read, run checks, reproduce the original scenario.
|
|
175
|
+
9. Confirm the original failure is resolved.
|
|
176
|
+
10. Check for regressions in related states and components.
|
|
177
|
+
|
|
178
|
+
## Avoid
|
|
179
|
+
|
|
180
|
+
- Editing code because it "looks like" the problem without verifying through inspection.
|
|
181
|
+
- Changing multiple files simultaneously before understanding the issue — each change obscures what fixed what.
|
|
182
|
+
- Rewriting a component to fix a problem that was in a single property.
|
|
183
|
+
- Adding CSS overrides that mask the real issue rather than correcting it.
|
|
184
|
+
- Hiding errors with try/catch or null checks without addressing the underlying cause.
|
|
185
|
+
- Disabling TypeScript or lint checks to make verification pass — if they flag something, investigate it.
|
|
186
|
+
- Declaring success before reproducing the original scenario with the fix applied.
|
|
187
|
+
- Inventing browser console output when browser tools are unavailable.
|
|
188
|
+
|
|
189
|
+
## Examples
|
|
190
|
+
|
|
191
|
+
### Example: Diagnosing layout overflow before editing
|
|
192
|
+
|
|
193
|
+
Wrong approach: "The component looks too wide, I'll add `overflow: hidden` to the parent."
|
|
194
|
+
|
|
195
|
+
Correct approach: Identify which specific element is causing overflow. Check `min-width` on flex children (common culprit). Inspect the box model of the overflowing element. Fix the constraint that prevents correct shrinking, not the visibility of the overflow.
|
|
196
|
+
|
|
197
|
+
### Example: State vs. rendering classification
|
|
198
|
+
|
|
199
|
+
Symptom: "The user's name shows the old value after they update their profile."
|
|
200
|
+
|
|
201
|
+
Classify first: Is the API returning the old value? Is the store not updating? Is the component not re-rendering? Is it re-rendering but showing a stale closure value? Each of these has a different fix. Read the data flow before editing.
|