@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/frontend-expert-guide.md

@@ -0,0 +1,342 @@
+# Frontend Expert Review Guide
+
+> 20-year experience distilled: Prevention over repair, UX first, systematic quality.
+
+## Table of Contents
+
+- [Core Philosophy](#core-philosophy)
+- [New Project Review](#new-project-review)
+- [Version Iteration Review](#version-iteration-review)
+- [New Feature Review](#new-feature-review)
+- [Common Problems & Solutions](#common-problems--solutions)
+- [Tools & Automation](#tools--automation)
+
+---
+
+## Core Philosophy
+
+1. **Prevention over repair** — Catch bugs before users see them
+2. **UX first** — Beautiful code is useless if the feature doesn't work
+3. **Type safety** — TypeScript strict mode prevents 40% of runtime errors
+4. **Component isolation** — Test in Storybook before integration
+5. **Performance by default** — Bundle size, Core Web Vitals from day one
+
+---
+
+## New Project Review
+
+### Architecture Checklist
+
+| Aspect | What to Verify | Red Flags |
+|--------|----------------|-----------|
+| **Component Structure** | Atomic design, separation of concerns | God components, mixed logic/UI |
+| **State Management** | Appropriate tool (Zustand/Redux/Context) | Global state abuse, prop drilling |
+| **Routing** | Lazy loading, code splitting | All routes in single bundle |
+| **API Layer** | Centralized, typed, error handling | Scattered fetch calls, no types |
+| **Styling** | CSS-in-JS or Tailwind, design tokens | Inline styles, magic numbers |
+
+### Technical Decisions Review
+
+```markdown
+## New Project Technical Review
+
+### Tech Stack Validation
+- [ ] Framework choice justified (React/Vue/Svelte)
+- [ ] TypeScript strict mode enabled
+- [ ] Linting and formatting configured (ESLint + Prettier)
+- [ ] Test framework setup (Jest + RTL or Vitest)
+- [ ] Build tool optimized (Vite over Webpack for new projects)
+
+### Performance Foundation
+- [ ] Bundle analyzer configured
+- [ ] Lazy loading strategy defined
+- [ ] Image optimization pipeline
+- [ ] CDN configuration planned
+- [ ] Core Web Vitals targets set (LCP <2.5s, FID <100ms, CLS <0.1)
+
+### Developer Experience
+- [ ] Hot module replacement working
+- [ ] Component development environment (Storybook)
+- [ ] Git hooks for pre-commit checks (Husky)
+- [ ] Documentation for onboarding
+```
+
+### Common New Project Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| Over-engineering | Delayed launch, complexity | Start simple, evolve architecture |
+| No design system | UI inconsistency | Establish tokens day one |
+| Skipping TypeScript | Runtime errors | Mandate strict mode |
+| No test infrastructure | Untestable code | Setup tests before first feature |
+| Ignoring accessibility | Legal risk, UX debt | a11y audit from start |
+
+---
+
+## Version Iteration Review
+
+### Compatibility Checklist
+
+| Check | Method | Risk if Skipped |
+|-------|--------|-----------------|
+| **Browser support** | Browserslist + Babel | Crashes on old browsers |
+| **API compatibility** | Version headers | Breaking client apps |
+| **State migration** | LocalStorage upgrade script | Lost user data |
+| **Feature deprecation** | Console warnings | Sudden breaks |
+
+### Regression Prevention
+
+```markdown
+## Iteration Regression Checklist
+
+### Before Merge
+- [ ] All existing tests pass
+- [ ] No snapshot test changes without review
+- [ ] Visual regression tests (Percy/Chromatic)
+- [ ] Performance benchmarks stable
+- [ ] Bundle size not increased significantly
+
+### Deployment Safety
+- [ ] Canary deployment configured
+- [ ] A/B testing for major changes
+- [ ] Rollback procedure documented
+- [ ] Monitoring alerts configured
+- [ ] Error tracking ready (Sentry)
+```
+
+### State Management Evolution
+
+```typescript
+// 🔴 BAD: State mutation during iteration
+const [items, setItems] = useState(oldItems);
+items.push(newItem); // Direct mutation!
+setItems(items);
+
+// ✅ GOOD: Immutable update pattern
+setItems(prev => [...prev, newItem]);
+
+// 🔴 BAD: Stale closure in iteration
+useEffect(() => {
+  const interval = setInterval(() => {
+    setCount(count + 1); // count is stale!
+  }, 1000);
+}, []); // Missing dependency
+
+// ✅ GOOD: Functional update
+useEffect(() => {
+  const interval = setInterval(() => {
+    setCount(c => c + 1);
+  }, 1000);
+  return () => clearInterval(interval);
+}, []);
+```
+
+---
+
+## New Feature Review
+
+### Feature Isolation Checklist
+
+| Aspect | Verification | Red Flag |
+|--------|--------------|----------|
+| **Scope boundary** | Feature flag wrapped | Global state changes |
+| **Component isolation** | Storybook stories exist | Depends on app context |
+| **API contract** | Types match backend | Field name mismatches |
+| **Error states** | Loading, error, empty handled | Only happy path |
+| **Mobile support** | Responsive, touch-friendly | Desktop-only design |
+
+### Feature Development Workflow
+
+```markdown
+## Feature Review Workflow
+
+### 1. Design Review
+- [ ] UI matches Figma/design spec
+- [ ] All states designed (loading, error, empty, success)
+- [ ] Responsive breakpoints defined
+- [ ] Accessibility requirements clear
+
+### 2. Implementation Review
+- [ ] TypeScript types defined
+- [ ] Components follow atomic design
+- [ ] State management appropriate
+- [ ] API integration typed
+- [ ] Error handling complete
+
+### 3. Testing Review
+- [ ] Unit tests for logic
+- [ ] Integration tests for API
+- [ ] Visual tests for UI
+- [ ] A11y tests passing
+- [ ] Edge cases covered
+
+### 4. Performance Review
+- [ ] No unnecessary re-renders
+- [ ] Lazy loaded if large
+- [ ] Images optimized
+- [ ] Bundle impact measured
+```
+
+### Concurrency & Race Conditions
+
+```typescript
+// 🔴 BAD: Race condition in search
+const [query, setQuery] = useState('');
+const [results, setResults] = useState([]);
+
+useEffect(() => {
+  fetch(`/search?q=${query}`)
+    .then(res => res.json())
+    .then(setResults); // Race condition: old response overwrites new
+}, [query]);
+
+// ✅ GOOD: Abort controller for race prevention
+useEffect(() => {
+  const controller = new AbortController();
+  
+  fetch(`/search?q=${query}`, { signal: controller.signal })
+    .then(res => res.json())
+    .then(setResults)
+    .catch(err => {
+      if (err.name !== 'AbortError') throw err;
+    });
+  
+  return () => controller.abort();
+}, [query]);
+```
+
+---
+
+## Common Problems & Solutions
+
+### Problem Matrix
+
+| Problem | Symptom | Root Cause | Solution |
+|---------|---------|------------|----------|
+| **Requirement churn** | Frequent rewrite | No frozen spec | Feature flags, weekly review |
+| **Wrong tech stack** | Maintenance pain | No POC | Prototype 2-3 options |
+| **Bundle bloat** | Slow load | Full imports | Tree shaking, dynamic import |
+| **Style conflicts** | Inconsistent UI | No design system | Enforce tokens, component lib |
+| **Test gaps** | Production bugs | No strategy | Mutation testing, E2E |
+| **A11y violations** | User complaints | Afterthought | Audit from day one |
+
+### Performance Optimization Patterns
+
+```typescript
+// 🔴 BAD: Import entire library
+import _ from 'lodash';
+_.debounce(fn, 300);
+
+// ✅ GOOD: Import only what you need
+import debounce from 'lodash/debounce';
+debounce(fn, 300);
+
+// 🔴 BAD: Inline functions cause re-renders
+<Button onClick={() => handleClick(id)} />
+
+// ✅ GOOD: Memoized callback
+const handleClick = useCallback(() => {
+  doSomething(id);
+}, [id]);
+<Button onClick={handleClick} />
+
+// 🔴 BAD: Expensive computation every render
+const sorted = items.sort((a, b) => a.name.localeCompare(b.name));
+
+// ✅ GOOD: Memoized computation
+const sorted = useMemo(
+  () => items.sort((a, b) => a.name.localeCompare(b.name)),
+  [items]
+);
+```
+
+---
+
+## Tools & Automation
+
+### Recommended Tool Stack
+
+| Category | Tool | Purpose |
+|----------|------|---------|
+| **Type Safety** | TypeScript (strict) | Prevent runtime errors |
+| **Linting** | ESLint + Prettier | Code consistency |
+| **Testing** | Jest + RTL + Cypress | Coverage pyramid |
+| **Performance** | Lighthouse CI | Core Web Vitals |
+| **A11y** | axe-core | Accessibility audit |
+| **Monitoring** | Sentry | Error tracking |
+| **Bundle** | Webpack Bundle Analyzer | Size optimization |
+
+### CI/CD Pipeline Requirements
+
+```yaml
+# Minimum frontend CI checks
+- lint: ESLint --max-warnings 0
+- types: tsc --noEmit
+- test: jest --coverage --threshold 80
+- build: vite build
+- audit: npm audit --audit-level high
+- a11y: axe-core scan
+- lighthouse: Performance budget check
+```
+
+### Pre-commit Hooks
+
+```json
+// .husky/pre-commit
+{
+  "hooks": {
+    "pre-commit": "lint-staged"
+  }
+}
+
+// lint-staged.config.js
+{
+  "*.{ts,tsx}": [
+    "eslint --fix",
+    "prettier --write",
+    "jest --findRelatedTests"
+  ]
+}
+```
+
+---
+
+## Review Report Template
+
+```markdown
+# Frontend Code Review Report
+
+## Summary
+- **Reviewer**: [Name]
+- **Date**: [Date]
+- **Context**: [New Project / Iteration / Feature]
+- **Verdict**: [APPROVED / CHANGES REQUESTED]
+
+## Findings
+
+### 🔴 P0 - Blockers
+| Issue | File:Line | Impact | Suggested Fix |
+|-------|-----------|--------|---------------|
+
+### 🟠 P1 - Critical
+| Issue | File:Line | Impact | Suggested Fix |
+|-------|-----------|--------|---------------|
+
+### 🟡 P2 - Major
+| Issue | File:Line | Impact | Suggested Fix |
+|-------|-----------|--------|---------------|
+
+## Checklist Completion
+- [ ] TypeScript types correct
+- [ ] Tests adequate
+- [ ] Performance acceptable
+- [ ] Accessibility verified
+- [ ] Mobile responsive
+- [ ] Error handling complete
+
+## Similar Bug Hunt
+**Pattern searched**: [Description]
+**Files checked**: [Count]
+**Issues found**: [Count]
+```
+