skillstore-cli 1.0.0

package/data/shared/framework/skills/frontend-development/references/troubleshooting.md

@@ -0,0 +1,154 @@
+# Frontend Troubleshooting Guide
+
+## Hydration Mismatch Errors (SSR/SSG)
+
+**Symptoms:** Console warning "Text content does not match server-rendered HTML", UI flickers on load.
+
+**Common causes and fixes:**
+1. **Browser-only APIs used during render** — `window`, `localStorage`, `navigator` accessed unconditionally.
+   - Fix: Guard with `useEffect` or `typeof window !== 'undefined'` checks.
+2. **Date/time formatting** — Server and client produce different locale strings.
+   - Fix: Use UTC formatting or suppress hydration for that element with `suppressHydrationWarning`.
+3. **Browser extensions injecting DOM nodes** — Extensions add elements between server HTML and hydration.
+   - Fix: Test in incognito. Not a code bug, but wrap dynamic sections in a client boundary.
+4. **Conditional rendering based on auth/state** — Server has no session, client does.
+   - Fix: Render skeleton on server, populate on client via `useEffect`.
+
+**Debug command:** Open DevTools Console, filter for "hydration". React 18+ logs the exact DOM diff.
+
+## "Cannot read property of undefined" State Bugs
+
+**Diagnosis workflow:**
+1. Check the stack trace — identify which property access fails.
+2. Trace the data flow backward: component props → parent state → API response → backend.
+3. Common root causes:
+   - API response shape changed (missing nested object).
+   - Race condition: component renders before async data arrives.
+   - Optional chaining missing on deeply nested access.
+
+**Fix patterns:**
+- Add optional chaining: `user?.profile?.name` instead of `user.profile.name`.
+- Set default values in destructuring: `const { items = [] } = data || {}`.
+- Add loading/error states that prevent rendering until data is valid.
+- Use TypeScript strict null checks to catch these at compile time.
+
+## CSS Specificity Wars Diagnosis
+
+**Symptoms:** Styles not applying, `!important` scattered everywhere, styles work in isolation but break in context.
+
+**Debug workflow:**
+1. Open DevTools → Elements → Computed tab → find the property → see which rule wins.
+2. Check the specificity: inline (1000) > #id (100) > .class (10) > element (1).
+3. Look for third-party CSS loaded after your styles that overrides them.
+
+**Fix patterns:**
+- Use CSS Modules or CSS-in-JS to scope styles and avoid collisions.
+- Increase specificity with a parent selector rather than `!important`.
+- Use `:where()` (zero specificity) for resets, `:is()` to group selectors.
+- Audit with: `document.querySelectorAll('[style]')` to find rogue inline styles.
+
+## Bundle Size Sudden Increase Investigation
+
+**Diagnosis workflow:**
+```bash
+# Install analyzer
+npm install --save-dev webpack-bundle-analyzer
+
+# Next.js: add to next.config.js
+# const withBundleAnalyzer = require('@next/bundle-analyzer')({ enabled: process.env.ANALYZE === 'true' })
+ANALYZE=true npm run build
+
+# Vite: use rollup-plugin-visualizer
+npx vite-bundle-visualizer
+```
+
+**Common culprits:**
+1. **Barrel file imports** — `import { Button } from '@/components'` pulls entire directory.
+   - Fix: Import directly from the file: `import { Button } from '@/components/Button'`.
+2. **Moment.js or similar heavy library added** — Check for locale bundles.
+   - Fix: Switch to `date-fns` or `dayjs` with tree-shaking.
+3. **Source maps included in production** — `devtool: 'source-map'` in prod config.
+4. **Missing dynamic imports** — Large page components loaded eagerly.
+   - Fix: `React.lazy()` + `Suspense` or Next.js `dynamic()`.
+
+## Memory Leaks in SPA
+
+**Symptoms:** Page slows down over time, tab memory in Task Manager grows continuously.
+
+**Detection:**
+1. DevTools → Memory → Take Heap Snapshot before and after navigating.
+2. Compare snapshots: filter by "Detached" to find detached DOM trees.
+3. Performance Monitor → JS Heap Size — should stabilize, not grow.
+
+**Common causes:**
+1. **Event listeners not cleaned up** — `addEventListener` without `removeEventListener` in cleanup.
+   - Fix: Always return cleanup from `useEffect`.
+2. **Intervals/timers not cleared** — `setInterval` persists across navigation.
+   - Fix: `clearInterval` in `useEffect` cleanup.
+3. **Closures holding stale references** — Callback captures large objects.
+   - Fix: Use `useRef` for mutable values, nullify references in cleanup.
+4. **Third-party libraries not destroyed** — Chart.js, map libraries hold DOM references.
+   - Fix: Call `.destroy()` or `.dispose()` in cleanup.
+
+## CORS Errors Configuration Checklist
+
+**Error:** `Access to fetch has been blocked by CORS policy`.
+
+**Diagnosis:**
+1. Open Network tab → find the failed request → check for preflight (OPTIONS) request.
+2. Verify response headers: `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, `Access-Control-Allow-Headers`.
+
+**Fix checklist:**
+- [ ] Server returns `Access-Control-Allow-Origin` matching the request origin (not `*` if credentials used).
+- [ ] Preflight OPTIONS request returns 200/204 (not 404 or 500).
+- [ ] `Access-Control-Allow-Methods` includes the HTTP method used.
+- [ ] `Access-Control-Allow-Headers` includes custom headers (e.g., `Authorization`, `Content-Type`).
+- [ ] `Access-Control-Allow-Credentials: true` if sending cookies.
+- [ ] Proxy configured in dev server (`vite.config.ts` proxy or Next.js rewrites) to avoid CORS in development.
+
+## Performance Regression Debugging (Core Web Vitals)
+
+**LCP (Largest Contentful Paint) regression:**
+1. DevTools → Performance → record page load → find LCP marker.
+2. Check: Is the largest element an image? Add `fetchpriority="high"` and `loading="eager"`.
+3. Check: Font blocking render? Use `font-display: swap` and preload critical fonts.
+4. Check: Render-blocking CSS/JS? Defer non-critical resources.
+
+**CLS (Cumulative Layout Shift) regression:**
+1. DevTools → Performance → enable "Layout Shift Regions".
+2. Common causes: images without explicit `width`/`height`, dynamic content injected above viewport, web fonts causing reflow.
+3. Fix: Set dimensions on media elements, use `min-height` on dynamic containers.
+
+**INP (Interaction to Next Paint) regression:**
+1. DevTools → Performance → interact with the page → check "Total Blocking Time".
+2. Long tasks (>50ms) on main thread block interactions.
+3. Fix: Break work with `requestIdleCallback`, use `startTransition` for non-urgent updates, move computation to Web Workers.
+
+## React Re-render Storms
+
+**Symptoms:** UI is sluggish, components re-render on every keystroke or unrelated state change.
+
+**Diagnosis with React DevTools Profiler:**
+1. Install React DevTools → Profiler tab → enable "Record why each component rendered".
+2. Click record → interact with the UI → stop recording.
+3. Look for components rendering with reason "Parent re-rendered" when their props didn't change.
+
+**Common causes and fixes:**
+1. **Inline object/array props** — `<Child style={{ color: 'red' }} />` creates new reference each render.
+   - Fix: Hoist to a constant or `useMemo`.
+2. **Context provider value not memoized** — `<Ctx.Provider value={{ user, setUser }}>` re-renders all consumers.
+   - Fix: `useMemo` the value object, or split contexts (read vs write).
+3. **State stored too high** — Form input state in a top-level component re-renders the entire tree.
+   - Fix: Move state down to the closest component that needs it, or use `React.memo`.
+4. **Missing dependency array** — `useEffect(() => {...})` without deps runs every render.
+   - Fix: Add proper dependency array.
+
+**Quick audit command:**
+```javascript
+// Paste in console to log all re-renders
+const origRender = React.createElement;
+React.createElement = function(...args) {
+  if (typeof args[0] === 'function') console.count(args[0].name);
+  return origRender.apply(this, args);
+};
+```

package/data/shared/framework/skills/mobile-development/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: mobile-development
+description: React Native/Flutter development — component design, navigation, state management, platform-specific concerns, offline-first patterns
+---
+
+# Mobile Development
+
+## Triggers
+
+Activate this skill when:
+- Building a mobile app or adding a mobile feature
+- Implementing navigation, gestures, or native interactions
+- Fixing mobile-specific bugs (platform differences, device quirks)
+- Optimizing mobile performance (rendering, memory, startup time)
+- Handling offline scenarios, push notifications, or permissions
+- Setting up CI/CD for mobile builds (Fastlane, EAS, Codemagic)
+
+## Process
+
+### 1. Platform Assessment
+- Identify target platforms (iOS, Android, or both)
+- Define minimum OS versions and device targets
+- List native capabilities needed (camera, GPS, Bluetooth, payments)
+- Decide framework: React Native (JS ecosystem, hot reload) vs Flutter (Dart, pixel-perfect UI)
+- Check third-party SDK requirements (maps, analytics, crash reporting)
+
+### 2. Architecture Design
+Load: `references/mobile-patterns.md`
+
+- Define navigation structure (stack, tab, drawer, modal flows)
+- Choose state management: local → context/provider → global store
+- Plan data layer: API client, local database, sync strategy
+- Establish project structure (feature-based folders, shared modules)
+- Define platform-specific boundaries (shared logic vs native code)
+
+### 3. Component Implementation
+- Build screens top-down: navigation shell → screen layouts → components
+- Use platform-aware components where UI conventions differ (iOS vs Android)
+- Implement forms with validation and keyboard handling
+- Handle safe areas, notches, dynamic island, and system bars
+- Wire up deep linking and universal links
+
+### 4. Testing
+- Unit test business logic and utilities
+- Component/widget tests for interactive elements
+- E2E tests for critical flows (Detox for RN, integration_test for Flutter)
+- Test on real devices for permission flows and native features
+- Test offline scenarios and poor network conditions
+
+### 5. Performance Optimization
+Load: `references/mobile-performance.md`
+
+- Profile rendering (React DevTools / Flutter DevTools)
+- Optimize list rendering (FlatList/ListView best practices)
+- Reduce app startup time (lazy init, minimal splash work)
+- Minimize memory leaks (clean up listeners, subscriptions, timers)
+- Audit app size and apply asset optimization
+
+## References
+
+- [Mobile Patterns](references/mobile-patterns.md) — navigation, state, offline-first, push notifications, permissions
+- [Mobile Performance](references/mobile-performance.md) — rendering, memory, network, startup, battery, testing
+- [Troubleshooting](references/troubleshooting.md) — build failures iOS/Android, red screen, startup crashes, push notifications, app store rejections
+
+## Assets
+
+- [Sample Output](assets/sample-output.md) — architecture plan for a Food Delivery app in React Native

package/data/shared/framework/skills/mobile-development/assets/sample-output.md

@@ -0,0 +1,382 @@
+# Sample Output: Food Delivery App — React Native Architecture Plan
+
+## Project Overview
+
+**App**: QuickBite — Food delivery platform
+**Framework**: React Native (Expo managed workflow)
+**Target**: iOS 15+, Android 12+
+**Team**: 3 RN developers, 1 QA
+
+---
+
+## Navigation Structure
+
+### Tab Navigator (4 tabs)
+
+```
+┌─────────┬──────────┬──────────┬──────────┐
+│  Home   │  Search  │  Orders  │ Profile  │
+└────┬────┴────┬─────┴────┬─────┴────┬─────┘
+     │         │          │          │
+     ▼         ▼          ▼          ▼
+  HomeStack  SearchStack OrderStack ProfileStack
+```
+
+### Screen Map
+
+```typescript
+type RootTabParamList = {
+  HomeTab: NavigatorScreenParams<HomeStackParamList>;
+  SearchTab: NavigatorScreenParams<SearchStackParamList>;
+  OrdersTab: NavigatorScreenParams<OrderStackParamList>;
+  ProfileTab: NavigatorScreenParams<ProfileStackParamList>;
+};
+
+type HomeStackParamList = {
+  Home: undefined;
+  RestaurantDetail: { id: string };
+  MenuItem: { restaurantId: string; itemId: string };
+};
+
+type OrderStackParamList = {
+  OrderList: undefined;
+  OrderDetail: { orderId: string };
+  OrderTracking: { orderId: string };  // Real-time map
+};
+
+type CheckoutParamList = {
+  Cart: undefined;
+  DeliveryAddress: undefined;
+  Payment: undefined;
+  OrderConfirmation: { orderId: string };
+};
+```
+
+### Modal Flows (presented over tabs)
+
+| Flow | Screens | Trigger |
+|------|---------|---------|
+| Checkout | Cart → Address → Payment → Confirmation | Tap "Checkout" in cart |
+| Add Address | Map Picker → Address Form | Tap "+" in address list |
+| Rating | Star Rating → Comment → Submit | After order delivered |
+
+### Deep Linking
+
+```typescript
+const linking: LinkingOptions<RootTabParamList> = {
+  prefixes: ['quickbite://', 'https://quickbite.app'],
+  config: {
+    screens: {
+      HomeTab: {
+        screens: {
+          RestaurantDetail: 'restaurant/:id',
+          MenuItem: 'restaurant/:restaurantId/item/:itemId',
+        },
+      },
+      OrdersTab: {
+        screens: {
+          OrderTracking: 'orders/:orderId/track',
+        },
+      },
+    },
+  },
+};
+```
+
+---
+
+## State Management
+
+### Store Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  Server State                        │
+│              (TanStack Query)                        │
+│  restaurants, menu items, orders, user profile       │
+│  → Caching, background refetch, optimistic updates   │
+├─────────────────────────────────────────────────────┤
+│                  Client State                        │
+│                  (Zustand)                           │
+│  cart, delivery address, UI preferences              │
+│  → Persisted to MMKV for instant restore             │
+├─────────────────────────────────────────────────────┤
+│                  Ephemeral State                     │
+│              (useState / useRef)                     │
+│  form inputs, scroll position, animation values      │
+│  → No persistence needed                             │
+└─────────────────────────────────────────────────────┘
+```
+
+### Zustand Stores
+
+```typescript
+// stores/cart.ts — persisted to MMKV
+interface CartStore {
+  items: CartItem[];
+  deliveryAddress: Address | null;
+  promoCode: string | null;
+  addItem: (item: MenuItem, qty: number, options: ItemOption[]) => void;
+  removeItem: (cartItemId: string) => void;
+  updateQuantity: (cartItemId: string, qty: number) => void;
+  setAddress: (address: Address) => void;
+  applyPromo: (code: string) => void;
+  subtotal: () => number;
+  deliveryFee: () => number;
+  total: () => number;
+  clear: () => void;
+}
+
+// stores/auth.ts — persisted, contains tokens
+interface AuthStore {
+  token: string | null;
+  user: User | null;
+  isAuthenticated: boolean;
+  login: (credentials: LoginRequest) => Promise<void>;
+  logout: () => void;
+  refreshToken: () => Promise<void>;
+}
+```
+
+### TanStack Query Keys
+
+```typescript
+export const queryKeys = {
+  restaurants: {
+    all: ['restaurants'] as const,
+    nearby: (lat: number, lng: number) => ['restaurants', 'nearby', lat, lng] as const,
+    detail: (id: string) => ['restaurants', id] as const,
+    menu: (id: string) => ['restaurants', id, 'menu'] as const,
+  },
+  orders: {
+    all: ['orders'] as const,
+    active: ['orders', 'active'] as const,
+    detail: (id: string) => ['orders', id] as const,
+    tracking: (id: string) => ['orders', id, 'tracking'] as const,
+  },
+  user: {
+    profile: ['user', 'profile'] as const,
+    addresses: ['user', 'addresses'] as const,
+    paymentMethods: ['user', 'payment-methods'] as const,
+  },
+};
+```
+
+---
+
+## Offline-First Architecture
+
+### Strategy by Data Type
+
+| Data | Offline Strategy | Local Storage | Sync Priority |
+|------|-----------------|---------------|---------------|
+| Restaurant list | Cache, stale OK | TanStack Query cache | Low |
+| Menu items | Cache, stale OK | TanStack Query cache | Low |
+| Cart | Full offline support | Zustand + MMKV | High |
+| Active order | Cache + poll on reconnect | WatermelonDB | Critical |
+| User profile | Cache, sync on change | MMKV | Medium |
+| Order history | Cache, paginated | WatermelonDB | Low |
+
+### Sync Queue for Mutations
+
+```typescript
+// When offline: queue mutations
+const pendingMutations: PendingMutation[] = [
+  { id: 'pm_1', type: 'PLACE_ORDER', payload: orderData, createdAt: Date.now() },
+  { id: 'pm_2', type: 'UPDATE_ADDRESS', payload: addressData, createdAt: Date.now() },
+];
+
+// On reconnect: process in order
+// PLACE_ORDER → critical, retry 3x
+// UPDATE_ADDRESS → non-critical, retry 1x
+```
+
+### Network State Hook
+
+```typescript
+function useNetworkAwareQuery<T>(key: QueryKey, fn: QueryFunction<T>) {
+  const isOnline = useNetworkStatus();
+
+  return useQuery({
+    queryKey: key,
+    queryFn: fn,
+    enabled: isOnline,
+    staleTime: isOnline ? 30_000 : Infinity,  // Never refetch when offline
+    gcTime: 24 * 60 * 60 * 1000,  // Keep cache 24h
+  });
+}
+```
+
+---
+
+## Performance Budget
+
+| Metric | Target | Measurement |
+|--------|--------|-------------|
+| Cold start | < 1.5s | Flipper startup profiler |
+| TTI (Time to Interactive) | < 2.0s | First meaningful paint + interactive |
+| FlatList scroll | 60 FPS | Flipper FPS monitor |
+| Image load | < 500ms | FastImage cache hit ratio |
+| API response display | < 300ms | Query + render time |
+| App size (iOS) | < 50MB | Xcode archive |
+| App size (Android) | < 30MB | AAB + APK analyzer |
+| JS bundle | < 2MB | Metro bundle size |
+| Memory (steady state) | < 200MB | Xcode Memory Graph |
+
+### FlatList Optimization
+
+```typescript
+<FlatList
+  data={restaurants}
+  renderItem={renderRestaurantCard}
+  keyExtractor={(item) => item.id}
+  getItemLayout={(_, index) => ({
+    length: CARD_HEIGHT,
+    offset: CARD_HEIGHT * index,
+    index,
+  })}
+  windowSize={5}
+  maxToRenderPerBatch={5}
+  removeClippedSubviews={true}
+  initialNumToRender={10}
+/>
+```
+
+### Image Strategy
+
+```typescript
+// Use expo-image (Expo) or FastImage (bare) with preloading
+<Image
+  source={{ uri: restaurant.imageUrl }}
+  style={styles.image}
+  placeholder={blurhash}
+  contentFit="cover"
+  transition={200}
+  cachePolicy="memory-disk"
+/>
+```
+
+---
+
+## CI/CD Pipeline
+
+### EAS Build + EAS Update
+
+```
+Feature Branch → PR
+  ├── Lint + Type Check (GitHub Actions, ~2 min)
+  ├── Unit Tests (Jest, ~3 min)
+  └── E2E Tests (Detox on iOS simulator, ~10 min)
+
+Merge to develop
+  └── EAS Update (OTA) → Internal testing channel
+
+Merge to main
+  ├── EAS Build (iOS + Android, ~20 min)
+  ├── TestFlight upload (iOS)
+  ├── Internal track upload (Android)
+  └── Sentry release + source maps
+
+Release
+  ├── App Store submission (manual trigger)
+  └── Play Store promotion (internal → production)
+```
+
+### Environment Config
+
+```typescript
+// app.config.ts — Expo config
+export default ({ config }: ConfigContext): ExpoConfig => ({
+  ...config,
+  extra: {
+    apiUrl: process.env.API_URL ?? 'https://api.quickbite.app',
+    sentryDsn: process.env.SENTRY_DSN,
+    mapboxToken: process.env.MAPBOX_TOKEN,
+    eas: { projectId: process.env.EAS_PROJECT_ID },
+  },
+});
+```
+
+---
+
+## Testing Strategy
+
+### Testing Pyramid
+
+```
+         ┌─────┐
+         │ E2E │  10% — Critical flows only
+         │Detox│  (order placement, auth, payment)
+        ┌┴─────┴┐
+        │ Integ │  30% — Screen-level tests
+        │ RNTL  │  (render + interaction + navigation)
+       ┌┴───────┴┐
+       │  Unit   │  60% — Business logic, hooks, utils
+       │  Jest   │  (stores, API transforms, validators)
+       └─────────┘
+```
+
+### Unit Test Example
+
+```typescript
+// __tests__/stores/cart.test.ts
+describe('CartStore', () => {
+  beforeEach(() => useCartStore.getState().clear());
+
+  it('calculates total with delivery fee', () => {
+    const { addItem, total, deliveryFee } = useCartStore.getState();
+    addItem(mockMenuItem, 2, []);  // $12.99 each
+    expect(total()).toBe(25.98 + deliveryFee());
+  });
+
+  it('applies promo code discount', () => {
+    const { addItem, applyPromo, total } = useCartStore.getState();
+    addItem(mockMenuItem, 1, []);
+    applyPromo('SAVE20');  // 20% off
+    expect(total()).toBeCloseTo(12.99 * 0.8 + 3.99);  // + delivery
+  });
+});
+```
+
+### E2E Critical Flow
+
+```typescript
+// e2e/orderPlacement.test.ts
+describe('Order Placement', () => {
+  beforeAll(async () => { await device.launchApp(); await loginAs('test@user.com'); });
+
+  it('completes full order flow', async () => {
+    // Browse
+    await element(by.id('restaurant-card-0')).tap();
+    await element(by.id('menu-item-0')).tap();
+    await element(by.id('add-to-cart')).tap();
+
+    // Checkout
+    await element(by.id('cart-button')).tap();
+    await element(by.id('checkout-button')).tap();
+    await element(by.id('address-0')).tap();
+    await element(by.id('pay-button')).tap();
+
+    // Confirmation
+    await expect(element(by.text('Order Confirmed'))).toBeVisible();
+    await expect(element(by.id('order-tracking-map'))).toBeVisible();
+  });
+});
+```
+
+---
+
+## Key Architecture Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Framework | Expo managed | OTA updates, EAS Build, no native config maintenance |
+| Navigation | React Navigation 7 | Most mature, type-safe, deep linking support |
+| Client state | Zustand + MMKV | Minimal boilerplate, fast persistence |
+| Server state | TanStack Query v5 | Caching, background refetch, optimistic updates |
+| Maps | react-native-maps + Mapbox | Real-time driver tracking needs custom tiles |
+| Payments | Stripe React Native SDK | PCI compliance handled by Stripe |
+| Push | Expo Notifications + FCM | Unified API, background handling |
+| Crash reporting | Sentry | Source map support, breadcrumbs, performance monitoring |
+| Analytics | PostHog | Self-hostable, funnel analysis, feature flags |
+| Local DB | WatermelonDB | Lazy loading, offline-first, observable queries |