Smithery is now a part of Arcade.dev! Read more in our announcement here
Apply fixes to entities/components with best practice validation...
Apply targeted fixes to your codebase while ensuring they follow best practices, maintain performance, and don't break architectural patterns.
Use this skill when:
Expected outcome: Clear implementation plan with before/after code, validation steps, and testing strategy.
Before diving in, answer these three questions to clarify the fix scope:
Examples:
Your answer: ___________________________________________
Describe the gap:
Your answer: ___________________________________________
Initial hypothesis:
Your answer: ___________________________________________
Goal: Understand the issue in detail
Steps:
Output:
Goal: Find simpler patterns before writing custom code
Steps:
Identify relevant libraries:
Search Context7 for documentation:
Use mcp__context7__resolve-library-id to find library ID
Use mcp__context7__get-library-docs to fetch docs
Look for code examples matching your use case
Check for built-in features:
Identify best practices violations:
Output:
When preserving or updating component JSDoc, validate against the standardized template.
ā Technical Description - One-line summary of what prop does ā Triplex Annotations - @min/@max/@step/@type/@enum/@default where applicable
ā "When to adjust" - Contextual guidance for when to change this prop ā "Typical range" - Visual landmarks with descriptive labels (Dim/Standard/Bright) ā "Interacts with" - List of related props (comma-separated)
āŖ Detailed Explanation - Only if technical description needs more context āŖ "Performance note" - Only if significant performance impact
ā Bad JSDoc (Missing Contextual Guidance):
/**
* The intensity.
* @default 0.4
*/
intensity?: number;
ā Good JSDoc (Complete Template):
/**
* Ambient light intensity (non-directional base illumination).
*
* **When to adjust:** Dark backgrounds (0.4-0.6), light backgrounds (0.1-0.3)
* **Typical range:** Dim (0.2) ā Standard (0.4) ā Bright (0.6)
* **Interacts with:** backgroundColor, keyIntensity
*
* @min 0 @max 1 @step 0.05
* @default 0.4 (balanced visibility)
*/
ambientIntensity?: number;
When fixing props, reference their documentation location:
ā Cite specific files and line numbers:
src/entities/breathingSphere/index.tsx:180-187 (sphere color props)src/entities/lighting/index.tsx:143-152 (lighting props)src/entities/environment/index.tsx:189-201 (environment props)ā Link to centralized defaults if applicable:
src/config/sceneDefaults.ts - VISUAL_DEFAULTS, LIGHTING_DEFAULTSā Verify 171+ prop system structure:
Check for single source of truth violations:
ā Duplicate Defaults (Bad):
// constants.ts
export const SPHERE_COLOR = '#4A8A9A';
// BreathingSphere.tsx
export function BreathingSphere({
colorExhale = '#4A8A9A', // Duplicate!
}) {}
// BreathingLevel.tsx
export function BreathingLevel({
sphereColorExhale = '#4A8A9A', // Triple duplicate!
}) {}
ā Single Source of Truth (Good):
// BreathingSphere.tsx (entity owns default)
export function BreathingSphere({
colorExhale = '#4A8A9A',
}) {}
// BreathingLevel.tsx (scene passes through)
export function BreathingLevel({
sphereColorExhale, // undefined, lets entity use its default
}) {
return <BreathingSphere colorExhale={sphereColorExhale} />;
}
Verify scene components follow the pattern:
ā Scene owns only what it renders directly:
ā Scene passes through entity props as undefined:
ā Entity components use their own defaults:
Goal: Design the fix with clear rationale
Steps:
Identify fix type:
Propose concrete changes:
Compare approaches:
Identify trade-offs:
Output:
Goal: Ensure fix won't break anything
Checklist:
For breathing-related fixes specifically:
Output:
Goal: Apply fix with clear documentation
Steps:
Code comment pattern:
// BEFORE: Parameter too subtle (Ā±10% variation)
breathPulseIntensity: 0.2,
// AFTER: Clearly visible (Ā±30% variation) - increased for better visual feedback
// during breathing cycle. Remains smooth at 60fps with eased motion.
breathPulseIntensity: 0.6,
Output:
Goal: Verify fix works and doesn't break anything
Steps:
Run dev server:
npm run dev
Visual validation:
Performance validation:
Integration validation:
Generate validation report:
Output:
Use this checklist for every fix you apply:
See Best Practices Reference for detailed patterns.
When to use: Any fix affecting particles, sphere, or breathing-related behavior
How it works:
Your fix ā breath-synchronization Mode 2 (Validate) ā get 8-point validation report
ā phase-by-phase behavior analysis
ā parameter range verification
ā damping constant check
Result: Confidence that fix maintains breathing synchronization correctness
See breath-synchronization skill for validation details.
When to use: Any fix affecting systems, traits, or entity behavior
How it works:
Your fix ā verify ECS patterns ā ensure trait immutability
ā check system order
ā validate data flow
When to use: Any fix affecting visual parameters or Triplex-editable components
How it works:
Your fix ā preserve JSDoc annotations (@min/@max/@step)
ā maintain visual editor compatibility
ā ensure Triplex can modify parameters
When to use: Visual parameter feels wrong (too subtle or too exaggerated)
Example: Particle breathing visibility issue
// BEFORE: barely visible
breathPulseIntensity: 0.2, // Ā±10% variation
// AFTER: clearly visible
breathPulseIntensity: 0.6, // Ā±30% variation
Validation approach:
Success criteria:
When to use: Custom code could use simpler library feature
Example: Custom easing instead of built-in lerp
// BEFORE: custom implementation
position.x += (target - position.x) * 0.1;
// AFTER: library native
position.x = THREE.MathUtils.lerp(position.x, target, 0.1);
Validation approach:
Success criteria:
When to use: Performance bottleneck identified in profiling
Example: Reduce damping lag for responsiveness
// BEFORE: slow response
{ trait: breathPhase, targetTrait: targetBreathPhase, speed: 0.1 } // 166ms lag
// AFTER: faster response
{ trait: breathPhase, targetTrait: targetBreathPhase, speed: 0.3 } // 55ms lag
Validation approach:
Success criteria:
When documenting a fix, use this template:
## Example: [Fix Name]
**Problem:** [What was wrong]
**Investigation:** [What you found]
**Approach:** [Conservative/Moderate/Bold - why chosen]
### Files Changed
1. `path/file.ts:line` - Change description
### Changes
**Before:**
```typescript
[original code]
After:
[new code]
// Added comment explaining why
Rationale: [Why this change]
---
## Rollback Strategy
For every fix, document how to revert:
```markdown
## If Issues Occur
**Animation too exaggerated:**
- Reduce breathPulseIntensity by 0.1 until balanced
- Test at 0.5, 0.4 if needed
**Full Rollback:**
[Show original values for all changed lines]
Skill-specific:
Shared references:
Related skills:
Let's apply fixes with confidence! š
