@buivietphi/skill-mobile-mt 1.0.0

package/shared/anti-patterns.md

@@ -0,0 +1,407 @@
+# Anti-Pattern Detection — Scan for Common Mistakes
+
+> Auto-detect patterns that cause crashes, leaks, or store rejections.
+
+## When to Use
+
+- Before committing code
+- During code review
+- When instrumentation/observability code is added
+- Before PR submission
+
+---
+
+## Detection Categories
+
+### 1. PII (Personally Identifiable Information) Leaks
+
+**CRITICAL** - Compliance risk (GDPR, CCPA, HIPAA)
+
+```
+PATTERNS TO DETECT:
+❌ email / phone / ssn / credit_card / address / dob (date of birth)
+❌ properties: ["user_email": user.email]
+❌ tags: ["phone": user.phone]
+❌ trackEvent("login", ["ssn": ssn])
+❌ console.log("User: ${user.email}")
+
+✅ SAFE ALTERNATIVES:
+✓ properties: ["has_email": user.email != nil]
+✓ tags: ["user_tier": "premium"]  // Enum, not PII
+✓ trackEvent("login", ["user_type": userType])
+✓ console.log("User: ${user.id}")  // UUID, not PII
+```
+
+**Auto-Fix Suggestion:**
+```
+Found: properties: ["email": user.email]
+Fix → properties: ["has_email": user.email != nil]
+
+Found: tags: ["user_id": userId]
+Fix → tags: ["user_tier": user.subscription.tier]
+```
+
+---
+
+### 2. High Cardinality
+
+**CRITICAL** - Explodes storage, kills query performance
+
+```
+PATTERNS TO DETECT:
+❌ user_id / session_id / uuid / timestamp / device_id as TAG values
+❌ tags: ["user_id": "uuid-123"]  // Unlimited unique values
+❌ tags: ["timestamp": Date.now()]  // Unbounded
+❌ dimensions: ["request_id": requestId]  // High cardinality
+
+✅ SAFE ALTERNATIVES:
+✓ tags: ["user_tier": "free|premium|enterprise"]  // Low cardinality (3 values)
+✓ tags: ["hour": date.getHours()]  // Low cardinality (0-23)
+✓ dimensions: ["status_code": "200|404|500"]  // Low cardinality
+
+RULE: Tags should have < 100 unique values over 30 days
+```
+
+**Auto-Fix Suggestion:**
+```
+Found: tags: ["user_id": userId]
+Why bad: user_id has unlimited unique values → storage explosion
+Fix →
+  Option 1: Remove tag (use session correlation instead)
+  Option 2: tags: ["user_tier": user.tier]  // Categorize
+  Option 3: Move to context field (not a tag)
+```
+
+---
+
+### 3. Unbounded Payloads
+
+**HIGH** - Hits size limits, network cost
+
+```
+PATTERNS TO DETECT:
+❌ Entire objects: extras: ["state": appState]
+❌ Large arrays: extras: ["cart": cart.items]  // If items can be 1000+
+❌ Unfiltered user input: extras: ["search_query": query]  // No length limit
+❌ Nested objects: extras: ["user": user]  // Can be recursive
+
+✅ SAFE ALTERNATIVES:
+✓ extras: ["cart_item_count": cart.items.count]  // Aggregate
+✓ extras: ["has_state": appState != nil]  // Boolean
+✓ extras: ["search_query_length": query.length]  // Derived
+✓ extras: ["user_tier": user.tier]  // Extract specific field
+
+RULE: Extras should be < 10KB total per event
+```
+
+**Auto-Fix Suggestion:**
+```
+Found: extras: ["cart": cart]
+Why bad: cart can be 1000+ items → 100KB+
+Fix →
+  extras: [
+    "cart_item_count": cart.items.count,
+    "cart_total": cart.total,
+    "cart_has_promo": cart.promo != nil
+  ]
+```
+
+---
+
+### 4. Unstructured Logs
+
+**MEDIUM** - Can't query or aggregate
+
+```
+PATTERNS TO DETECT:
+❌ String interpolation: console.log(`User ${userId} failed`)
+❌ Free-form text: log("Something went wrong")
+❌ Mixed formats: log("Error: code=500, user=123")
+
+✅ STRUCTURED ALTERNATIVES:
+✓ logger.error("user_login_failed", { user_id: userId, reason: "timeout" })
+✓ trackEvent("error", {
+    error_type: "login_failed",
+    user_id: userId,
+    reason: "timeout"
+  })
+```
+
+---
+
+### 5. Sync Telemetry on Main Thread
+
+**HIGH** - UI freezes
+
+```
+PATTERNS TO DETECT:
+❌ trackEvent(...) in render / build / Composable
+❌ captureError(...) without async / background
+❌ flush() on main thread
+❌ Network call inside instrumentation without queue
+
+✅ SAFE ALTERNATIVES:
+✓ trackEvent(...) → batches automatically (Sentry, Amplitude)
+✓ captureError(...) → sends async (Firebase Crashlytics)
+✓ Use background queue: DispatchQueue.global().async { ... }
+✓ InteractionManager.runAfterInteractions(() => { ... })
+```
+
+---
+
+### 6. Missing Context
+
+**MEDIUM** - Events without correlation
+
+```
+REQUIRED CONTEXT FOR EVERY EVENT:
+□ session_id (correlation)
+□ screen (where it happened)
+□ job_name (business goal: "checkout", "onboarding")
+□ job_step (which step: "cart_review", "payment")
+□ app_version (which release)
+
+PATTERNS TO DETECT:
+❌ trackEvent("button_tapped")  // What button? Which screen?
+❌ captureError(error)  // No context
+
+✅ COMPLETE EXAMPLES:
+✓ trackEvent("button_tapped", {
+    button: "checkout_submit",
+    screen: "CartScreen",
+    job_name: "checkout",
+    job_step: "cart_review",
+    session_id: sessionId,
+    app_version: "1.2.3"
+  })
+
+✓ captureError(error, {
+    screen: "PaymentScreen",
+    job_name: "checkout",
+    job_step: "payment",
+    session_id: sessionId
+  })
+```
+
+---
+
+### 7. Mobile-Specific Anti-Patterns
+
+#### React Native
+
+```
+❌ console.log in production (massive bottleneck)
+❌ require() in render (re-executes every frame)
+❌ Anonymous functions in FlatList renderItem
+❌ Inline styles in render
+❌ AsyncStorage for tokens (use SecureStore)
+
+✅ CORRECT:
+✓ __DEV__ && console.log(...)
+✓ const Component = React.lazy(() => import(...))
+✓ const renderItem = useCallback((item) => ..., [])
+✓ const styles = StyleSheet.create({ ... })
+✓ SecureStore.setItemAsync('token', token)
+```
+
+#### Flutter
+
+```
+❌ print() in production
+❌ setState in build()
+❌ Unbounded ListView (use ListView.builder)
+❌ SharedPreferences for tokens (use flutter_secure_storage)
+
+✅ CORRECT:
+✓ kDebugMode && print(...)
+✓ setState in event handlers, not build
+✓ ListView.builder(itemCount: items.length, ...)
+✓ await secureStorage.write(key: 'token', value: token)
+```
+
+#### iOS
+
+```
+❌ Force unwrap (!) without nil check
+❌ Retain cycles ([self] in closures)
+❌ UserDefaults for tokens (use Keychain)
+❌ Heavy work on main thread
+
+✅ CORRECT:
+✓ guard let value = optional else { return }
+✓ Capture [weak self] or [unowned self]
+✓ KeychainWrapper.standard.set(token, forKey: "token")
+✓ DispatchQueue.global().async { ... }
+```
+
+#### Android
+
+```
+❌ !! (force unwrap) without null check
+❌ Memory leaks (Activity/Context references)
+❌ SharedPreferences for tokens (use EncryptedSharedPreferences)
+❌ AsyncTask (deprecated, use WorkManager)
+
+✅ CORRECT:
+✓ val value = optional ?: return
+✓ Use ViewModel, avoid Activity refs in background
+✓ EncryptedSharedPreferences for sensitive data
+✓ WorkManager for background tasks
+```
+
+---
+
+## Detection Workflow
+
+```
+PRE-COMMIT HOOK:
+1. Scan all changed files for anti-patterns
+2. Flag CRITICAL (block commit) vs HIGH (warn) vs MEDIUM (suggest)
+3. Provide auto-fix suggestions
+4. Run again after fix
+
+DURING CODE REVIEW:
+1. Agent scans PR diff
+2. Comments on lines with anti-patterns
+3. Suggests fixes inline
+4. Links to this doc for explanation
+
+CONTINUOUS:
+1. Periodic full codebase scan
+2. Generate report: violations by severity
+3. Track trends (increasing/decreasing)
+4. Alert if CRITICAL violations increase
+```
+
+---
+
+## Severity Levels
+
+| Severity | Impact | Action |
+|----------|--------|--------|
+| **CRITICAL** | PII leak, compliance risk | Block commit/PR |
+| **HIGH** | Performance issue, crashes | Block commit, allow override |
+| **MEDIUM** | Code smell, maintainability | Warn, suggest fix |
+| **LOW** | Style, best practice | Suggest, don't block |
+
+---
+
+## Example: Full Detection Report
+
+```
+FILE: src/features/auth/LoginScreen.tsx
+LINE 45: ❌ CRITICAL - PII Leak
+  Found: trackEvent("login", { email: user.email })
+  Fix:   trackEvent("login", { has_email: user.email != nil })
+  Why:   Email is PII → GDPR/CCPA violation
+
+LINE 67: ❌ HIGH - High Cardinality
+  Found: tags: ["user_id": userId]
+  Fix:   tags: ["user_tier": user.tier]
+  Why:   user_id unbounded → storage explosion
+
+LINE 89: ❌ MEDIUM - Missing Context
+  Found: captureError(error)
+  Fix:   captureError(error, { screen: "LoginScreen", job_name: "auth" })
+  Why:   Can't correlate error without context
+
+FILE: src/services/analytics.ts
+LINE 23: ❌ CRITICAL - Sync Telemetry on Main Thread
+  Found: trackEvent(...) in render()
+  Fix:   Move to useEffect or InteractionManager.runAfterInteractions
+  Why:   Blocks UI rendering → janky experience
+
+Summary:
+  2 CRITICAL (block)
+  1 HIGH (warn)
+  1 MEDIUM (suggest)
+```
+
+---
+
+## Auto-Fix Templates
+
+### PII → Boolean
+```typescript
+// Before
+trackEvent("signup", { email: user.email })
+
+// After
+trackEvent("signup", { has_email: user.email !== undefined })
+```
+
+### High Cardinality → Enum
+```typescript
+// Before
+tags: ["user_id": userId]
+
+// After
+tags: ["user_tier": user.subscription.tier]  // "free" | "premium" | "enterprise"
+```
+
+### Unbounded → Aggregate
+```typescript
+// Before
+extras: ["cart": cart]
+
+// After
+extras: [
+  "cart_item_count": cart.items.length,
+  "cart_total_cents": cart.totalCents
+]
+```
+
+### Missing Context → Complete
+```typescript
+// Before
+trackEvent("button_tapped")
+
+// After
+trackEvent("button_tapped", {
+  button: "checkout_submit",
+  screen: "CartScreen",
+  job_name: "checkout",
+  job_step: "cart_review",
+  session_id: sessionManager.currentSessionId,
+  app_version: Constants.expoConfig?.version
+})
+```
+
+---
+
+## Integration with CI/CD
+
+```bash
+# Pre-commit hook
+.git/hooks/pre-commit:
+  npm run detect-anti-patterns -- --severity=critical --block
+
+# PR Check
+.github/workflows/pr-check.yml:
+  - name: Detect Anti-Patterns
+    run: npm run detect-anti-patterns -- --severity=high --report
+
+# Weekly Scan
+.github/workflows/weekly-scan.yml:
+  schedule: cron('0 0 * * 0')  # Every Sunday
+  run: npm run detect-anti-patterns -- --full-scan --report
+```
+
+---
+
+## Learning from AI Tools
+
+**Common mistakes AI tools make:**
+
+| Tool | Mistake | Why |
+|------|---------|-----|
+| Cursor | Logs PII directly | Doesn't know GDPR/CCPA |
+| Cline | Uses user_id as tag | Doesn't understand cardinality |
+| Windsurf | Passes entire state objects | Doesn't check payload size |
+| Devin | Sync telemetry on main thread | Doesn't profile performance impact |
+
+**This skill avoids these by:**
+- Scanning before commit
+- Auto-suggesting fixes
+- Blocking CRITICAL violations
+- Teaching best practices

package/shared/bug-detection.md

@@ -0,0 +1,71 @@
+# Bug Detection — Auto Scanner
+
+> Always loaded. All platforms.
+
+---
+
+## Scan Order (by severity)
+
+### 1. Crash Risks (CRITICAL)
+```
+├── Force unwrap (! / !! / non-null assertion)
+├── Array out of bounds
+├── Unhandled null on API response
+├── Missing try/catch on async ops
+├── Missing error boundaries (RN)
+├── Infinite recursion
+└── Division by zero
+```
+
+### 2. Memory Leaks (HIGH)
+```
+RN:      useEffect without cleanup, listeners not removed, timers not cleared
+Flutter: StreamSubscription/Controller not disposed
+iOS:     [weak self] missing, observers not removed
+Android: Context leak, BroadcastReceiver not unregistered
+```
+
+### 3. Race Conditions (HIGH)
+```
+├── Button tappable during async op → add isSubmitting flag
+├── setState after unmount → track mounted state
+├── Multiple 401s → queue token refresh
+└── Optimistic update without rollback → save previous state
+```
+
+### 4. Security (HIGH)
+```
+├── Hardcoded secrets → env / secure config
+├── Tokens in AsyncStorage/SharedPrefs → SecureStore/Keychain
+├── Sensitive data in logs → strip before logging
+├── Deep links unvalidated → validate params
+└── Debug mode in release → strip debug flags
+```
+
+### 5. Performance (MEDIUM)
+```
+├── ScrollView for long lists → FlatList/ListView.builder/LazyColumn
+├── Inline functions in render → useCallback/memo/const
+├── Index as key → stable unique ID
+├── Large images unoptimized → resize, cache
+├── Main thread blocking → background thread
+└── Missing pagination → add cursor/offset
+```
+
+### 6. UX (MEDIUM)
+```
+├── Touch targets < 44pt/48dp
+├── Missing loading/error/empty states
+├── No keyboard dismiss
+├── Missing safe area handling
+└── No accessibility labels
+```
+
+## Report Format
+
+```
+🐛 [SEVERITY] — [file:line]
+   Issue:  [description]
+   Impact: [what breaks]
+   Fix:    [code change]
+```

package/shared/claude-md-template.md

@@ -0,0 +1,125 @@
+# CLAUDE.md Template for Mobile Projects
+
+> Copy this file to your project root as `CLAUDE.md`.
+> Claude Code reads it automatically every session — no invocation needed.
+
+---
+
+## How to use
+
+1. Copy this file to your project: `cp CLAUDE.md.template CLAUDE.md`
+2. Edit the sections marked with `[FILL IN]`
+3. Claude will follow these rules automatically in every conversation
+
+---
+
+## Template (copy below this line)
+
+---
+
+# Project: [FILL IN: Your App Name]
+
+## Stack
+
+- **Framework:** [React Native CLI / Expo SDK XX / Flutter X.X / iOS / Android]
+- **Language:** [TypeScript / JavaScript / Dart / Swift / Kotlin]
+- **State:** [Redux Toolkit / Zustand / Riverpod / BLoC / StateFlow]
+- **Navigation:** [React Navigation v6 / Expo Router / GoRouter / UIKit / Jetpack]
+- **API:** [axios / fetch / Dio / Firebase / GraphQL]
+- **Package Manager:** [yarn / npm / pnpm / bun / flutter pub]
+
+## Project Structure
+
+```
+[FILL IN: paste your src/ or lib/ tree here]
+src/
+├── features/
+│   ├── auth/
+│   └── home/
+├── shared/
+│   ├── components/
+│   └── utils/
+```
+
+## Conventions
+
+- **Naming:** [PascalCase screens, camelCase hooks/services]
+- **Imports:** [absolute @/ aliases / relative paths]
+- **Styling:** [StyleSheet / NativeWind / styled-components / Compose / SwiftUI]
+
+## Auto-Check Rules (apply after EVERY code change)
+
+Before saying "done" on any task, automatically verify:
+
+```
+□ No console.log / print / NSLog in production code
+□ No hardcoded secrets, API keys, or tokens
+□ No token storage in AsyncStorage / SharedPreferences / UserDefaults
+□ All async operations wrapped in try/catch
+□ All 4 states handled: loading / error / empty / success
+□ useEffect / dispose / viewModelScope has cleanup
+□ FlatList (not ScrollView) for lists > 20 items
+□ No force unwrap (! / !! / as!) without null check
+□ TypeScript: no implicit 'any'
+□ New screens registered in navigator
+□ Imports resolve (no broken paths)
+```
+
+If ANY check fails → fix it before marking done.
+
+## Performance Rules (apply when building lists, animations, heavy screens)
+
+```
+□ FlatList with keyExtractor + getItemLayout (if fixed height)
+□ React.memo on list item components
+□ useCallback on handlers passed to list items
+□ Images: use FastImage / expo-image, specify width+height
+□ Animations: use react-native-reanimated (not Animated API)
+□ No heavy computation on main thread (use InteractionManager)
+```
+
+## Security Rules (non-negotiable)
+
+```
+□ Tokens → SecureStore / Keychain / EncryptedSharedPreferences ONLY
+□ Deep link params → validate before use
+□ API calls → HTTPS only
+□ Sensitive data → never in logs
+□ User input → sanitize before display (XSS)
+```
+
+## What NOT to do
+
+```
+□ NEVER suggest migrating to a different framework/architecture
+□ NEVER change state management library
+□ NEVER add packages without checking SDK compatibility first
+□ NEVER mix package managers (yarn + npm)
+□ NEVER create new files for one-off operations
+□ NEVER add comments to code you didn't change
+```
+
+## Preferred Commands
+
+```bash
+# Install
+[yarn install / npm install / flutter pub get / pod install]
+
+# Run
+[yarn ios / yarn android / flutter run / xcodebuild / ./gradlew]
+
+# Test
+[yarn test / flutter test / xcodebuild test]
+
+# Lint
+[yarn lint / flutter analyze / swiftlint]
+```
+
+## Notes
+
+[FILL IN: any project-specific quirks, known issues, or important context]
+
+Example:
+- Auth uses custom JWT refresh logic in src/services/auth/tokenManager.ts
+- Push notifications require manual certificate setup (see docs/push-setup.md)
+- Android flavor: 'staging' points to staging API, 'production' to prod