@buivietphi/skill-mobile-mt 1.0.0

package/shared/code-review.md

@@ -0,0 +1,121 @@
+# Code Review — Senior Protocol
+
+> 🔴 Always loaded. All platforms.
+
+---
+
+## Checklist
+
+### Architecture
+- [ ] Single responsibility per file (max 300 lines)
+- [ ] Dependencies flow inward (UI → Domain → Data)
+- [ ] Follows existing project patterns
+- [ ] New files in correct directory
+
+### Correctness
+- [ ] All states handled: loading, success, error, empty
+- [ ] Edge cases: null, empty, timeout, concurrent
+- [ ] Async errors caught with meaningful handling
+- [ ] Cleanup on unmount/dispose (listeners, timers, subscriptions)
+- [ ] No race conditions (double-tap, concurrent API calls)
+
+### Performance
+- [ ] Lists virtualized (FlatList / ListView.builder / LazyColumn)
+- [ ] Memoized where needed (memo / const / remember)
+- [ ] No inline functions in render/build
+- [ ] Images cached and resized
+- [ ] No main thread blocking
+
+### Security
+- [ ] No hardcoded secrets
+- [ ] Secure storage for tokens (Keychain / EncryptedSharedPreferences)
+- [ ] Input validated and sanitized
+- [ ] Deep links validated before navigation
+- [ ] No sensitive data in logs
+
+### Platform
+- [ ] Both iOS + Android tested (if cross-platform)
+- [ ] Safe areas / notch handled
+- [ ] Keyboard handled (dismiss, avoidance)
+- [ ] Back button handled (Android)
+- [ ] Accessibility labels on interactive elements
+
+---
+
+## Severity
+
+| Level | Action | Example |
+|-------|--------|---------|
+| 🔴 CRITICAL | Must fix before merge | Crash, security hole, data loss |
+| 🟠 HIGH | Should fix before merge | Memory leak, missing error state, race condition |
+| 🟡 MEDIUM | Fix in follow-up | Naming inconsistency, missing memoization |
+| 🔵 LOW | Nice to have | Minor style, comment improvement |
+
+---
+
+## Auto-Fail
+
+**Any of these → block merge immediately:**
+
+```
+❌ console.log / print in production code
+❌ Hardcoded secrets or API keys
+❌ Force unwrap without null check (! / !! / as!)
+❌ Empty catch blocks (error silently swallowed)
+❌ 500+ line files
+❌ Network call in render / build / Composable
+❌ Index as list key
+❌ Missing loading / error / empty state (blank screen)
+```
+
+---
+
+## Review Comment Templates
+
+```
+🔴 CRITICAL — [file:line]
+Issue: [description]
+Impact: [what breaks]
+Fix: [specific code change]
+
+🟠 HIGH — [file:line]
+Issue: [description]
+Fix: [suggestion]
+
+🟡 MEDIUM — [file:line]
+Suggestion: [improvement]
+```
+
+---
+
+## Example Issues
+
+### Before (Bad)
+```typescript
+// ❌ No error handling, no loading state, index as key
+function ProductList() {
+  const [data, setData] = useState([]);
+  useEffect(() => { api.get('/products').then(r => setData(r.data)); }, []);
+  return data.map((item, i) => <ProductCard key={i} item={item} />);
+}
+```
+
+### After (Good)
+```typescript
+// ✅ All states, cleanup, stable key, error handling
+function ProductList() {
+  const [state, setState] = useState({ data: [], loading: true, error: null });
+  useEffect(() => {
+    let cancelled = false;
+    api.get('/products')
+      .then(r => { if (!cancelled) setState({ data: r.data, loading: false, error: null }); })
+      .catch(e => { if (!cancelled) setState({ data: [], loading: false, error: e.message }); });
+    return () => { cancelled = true; };
+  }, []);
+
+  if (state.loading) return <LoadingSkeleton />;
+  if (state.error) return <ErrorView message={state.error} onRetry={refresh} />;
+  if (!state.data.length) return <EmptyState />;
+  return <FlatList data={state.data} keyExtractor={item => item.id} renderItem={...} />;
+}
+```

package/shared/common-pitfalls.md

@@ -0,0 +1,117 @@
+# Common Pitfalls — Problem → Symptoms → Solution
+
+> Cross-platform mobile mistakes. Learn from production incidents.
+
+---
+
+## 1. setState After Unmount
+
+| | |
+|--|--|
+| **Problem** | Async operation completes after screen is popped/unmounted |
+| **Symptoms** | "Can't perform a React state update on an unmounted component" / crash |
+| **Solution (RN)** | Track mounted state: `useRef` + cleanup in `useEffect` return |
+| **Solution (Flutter)** | Check `mounted` before `setState`, cancel in `dispose()` |
+| **Solution (iOS)** | Use `Task` with cancellation, `[weak self]` in closures |
+| **Solution (Android)** | Use `viewModelScope` (auto-cancels), `Lifecycle`-aware coroutines |
+
+## 2. Token Refresh Race Condition
+
+| | |
+|--|--|
+| **Problem** | Multiple 401 responses trigger multiple token refresh calls |
+| **Symptoms** | Duplicate refresh requests, token corruption, logout loops |
+| **Solution** | Queue all 401s, refresh once, replay queued requests with new token |
+
+## 3. List Performance (ScrollView Trap)
+
+| | |
+|--|--|
+| **Problem** | Using ScrollView / Column for dynamic lists |
+| **Symptoms** | Jank, high memory, slow render with 50+ items |
+| **Solution (RN)** | `FlatList` with `keyExtractor`, `getItemLayout`, `removeClippedSubviews` |
+| **Solution (Flutter)** | `ListView.builder` or `SliverList` (lazy rendering) |
+| **Solution (Android)** | `LazyColumn` with stable `key` |
+
+## 4. Memory Leak — Listeners Not Cleaned
+
+| | |
+|--|--|
+| **Problem** | Event listeners, subscriptions, timers created but never removed |
+| **Symptoms** | Memory grows over time, app slows down, eventual crash |
+| **Solution (RN)** | Always return cleanup in `useEffect`: `return () => listener.remove()` |
+| **Solution (Flutter)** | `StreamSubscription.cancel()` and `controller.dispose()` in `dispose()` |
+| **Solution (iOS)** | Remove `NotificationCenter` observers, cancel `Task`s |
+| **Solution (Android)** | Unregister `BroadcastReceiver`, cancel coroutine scopes |
+
+## 5. Hardcoded Strings / Magic Numbers
+
+| | |
+|--|--|
+| **Problem** | Colors, sizes, URLs, keys scattered as literals in code |
+| **Symptoms** | Inconsistent UI, hard to maintain, hard to theme |
+| **Solution** | Constants file for colors/spacing, env config for URLs/keys |
+
+## 6. Missing Error Boundaries
+
+| | |
+|--|--|
+| **Problem** | Uncaught error in one component crashes the entire app |
+| **Symptoms** | White screen of death, full app crash |
+| **Solution (RN)** | Wrap with `ErrorBoundary` component at screen/feature level |
+| **Solution (Flutter)** | `ErrorWidget.builder` + try/catch in async providers |
+| **Solution (iOS)** | Graceful error states in every View (`.error` case in ViewModel) |
+| **Solution (Android)** | Sealed `UiState` with `Error` case, never let exceptions propagate to UI |
+
+## 7. Deep Link Injection
+
+| | |
+|--|--|
+| **Problem** | Deep link parameters used directly without validation |
+| **Symptoms** | Navigation to unauthorized screens, data exposure |
+| **Solution** | Validate all deep link params (type, format, authorization) before navigating |
+
+## 8. Button Double-Tap
+
+| | |
+|--|--|
+| **Problem** | User taps submit button twice during async operation |
+| **Symptoms** | Duplicate API calls, duplicate records, charge twice |
+| **Solution** | `isSubmitting` flag — disable button during async operation |
+
+## 9. Large Images Unoptimized
+
+| | |
+|--|--|
+| **Problem** | Loading full-resolution images from server |
+| **Symptoms** | High memory, slow scroll, OOM crash on old devices |
+| **Solution** | Request resized images from CDN, use `cached_network_image` / `FastImage`, progressive loading |
+
+## 10. Missing Offline Handling
+
+| | |
+|--|--|
+| **Problem** | App assumes network is always available |
+| **Symptoms** | Crash or infinite loading when offline, data loss |
+| **Solution** | Cache critical data locally, show cached data + "offline" banner, queue operations for retry |
+
+## 11. Platform-Specific Ignoring
+
+| | |
+|--|--|
+| **Problem** | Testing only on iOS, shipping broken Android (or vice versa) |
+| **Symptoms** | Android back button doesn't work, keyboard covers input, notch/status bar overlap |
+| **Solution** | Test on BOTH platforms. Handle: back button, safe area, keyboard avoidance, permissions |
+
+## 12. Wrong Package Manager
+
+| | |
+|--|--|
+| **Problem** | Using `npm install` in a `yarn.lock` project |
+| **Symptoms** | Conflicting lock files, dependency resolution differs, CI fails |
+| **Solution** | Check lock file first. `yarn.lock` → yarn. `package-lock.json` → npm. Never mix. |
+
+---
+
+> Every pitfall here has caused a production incident.
+> Learn from others' mistakes.

package/shared/document-analysis.md

@@ -0,0 +1,167 @@
+# Document Analysis — Extract Requirements from Any File
+
+> Parse design files, specs, and documents into actionable mobile implementation tasks.
+
+## Supported Formats
+
+| Format | How to Read | Use Case |
+|--------|------------|----------|
+| **Images** (PNG, JPG, WebP) | Read tool (multimodal) | UI mockups, wireframes, screenshots |
+| **PDF** | Read tool (pages param, max 20/request) | PRD, API docs, design specs |
+| **DOCX** | Convert to text first | Requirements, user stories |
+| **XML** | Read tool directly | Android layouts, config, API response |
+| **JSON** | Read tool directly | API contracts, config, mock data |
+| **YAML** | Read tool directly | CI/CD config, OpenAPI specs |
+| **Figma** | URL → WebFetch | Design tokens, component specs |
+
+## Analysis Protocol
+
+### Step 1: Identify Document Type
+
+```
+DOCUMENT TYPE:
+  Image (mockup/wireframe)  → UI Analysis Protocol
+  PDF/DOCX (requirements)   → Requirements Extraction Protocol
+  XML/JSON (API contract)   → Data Model Protocol
+  Figma URL                 → Design Token Protocol
+```
+
+### Step 2: Extract by Type
+
+#### UI Analysis (Images)
+
+```
+FROM IMAGE, EXTRACT:
+  1. LAYOUT
+     - Screen structure (header, body, footer, tabs)
+     - Component hierarchy (parent → child)
+     - Spacing pattern (uniform? 8px grid? 16px?)
+
+  2. COMPONENTS
+     - List all visible UI elements
+     - Map to framework components:
+       Button, TextInput, FlatList, Image, Card, Modal, etc.
+     - Note interactive elements (tap, swipe, scroll)
+
+  3. STYLING
+     - Colors (primary, secondary, background, text)
+     - Typography (heading size, body size, font weight)
+     - Border radius, shadows, elevation
+     - Dark mode indicators (if visible)
+
+  4. STATES (infer from design)
+     - Loading: where to show skeleton/shimmer?
+     - Empty: what if list has no items?
+     - Error: where to show error message?
+
+OUTPUT → Component tree + style constants + state handling plan
+```
+
+#### Requirements Extraction (PDF/DOCX)
+
+```
+FROM DOCUMENT, EXTRACT:
+  1. USER STORIES
+     - "As a [user], I want [action], so that [benefit]"
+     - Priority: must-have / nice-to-have
+     - Acceptance criteria
+
+  2. SCREENS / FLOWS
+     - List all screens mentioned
+     - Map navigation flow (Screen A → Screen B → Screen C)
+     - Identify entry points and exit points
+
+  3. DATA REQUIREMENTS
+     - What data does each screen need?
+     - API endpoints mentioned
+     - Data relationships (user has many orders)
+
+  4. BUSINESS RULES
+     - Validation rules (email format, password strength)
+     - Permission levels (admin, user, guest)
+     - Edge cases mentioned
+
+  5. NON-FUNCTIONAL
+     - Performance requirements (load time, offline support)
+     - Platform requirements (iOS min version, Android min SDK)
+     - Accessibility requirements
+
+OUTPUT → Feature list + screen map + data model + API contract
+```
+
+#### Data Model Protocol (XML/JSON)
+
+```
+FROM API CONTRACT, EXTRACT:
+  1. ENDPOINTS
+     - Method + URL + description
+     - Request params / body
+     - Response shape
+
+  2. MODELS / TYPES
+     - Generate TypeScript interfaces / Dart classes / Swift structs / Kotlin data classes
+     - Include optional fields, enums, nested objects
+     - Add serialization annotations if needed
+
+  3. ERROR RESPONSES
+     - Error code mapping
+     - Error message display strategy
+
+OUTPUT → Type definitions + API service layer + error handling
+```
+
+## Document → Code Pipeline
+
+```
+STEP 1: READ DOCUMENT
+  - Image: Read tool (visual analysis)
+  - PDF: Read tool with pages param
+  - DOCX/XML/JSON: Read tool directly
+  - Large PDF (>20 pages): Read in chunks (pages: "1-20", "21-40", etc.)
+
+STEP 2: EXTRACT REQUIREMENTS
+  - Run appropriate extraction protocol above
+  - Output structured summary
+
+STEP 3: MAP TO FEATURES
+  - Group requirements into features
+  - Identify dependencies between features
+  - Prioritize: auth → core screens → secondary features
+
+STEP 4: SCAFFOLD
+  - Use Feature Scaffold Protocol from SKILL.md
+  - Create features in dependency order
+  - Wire navigation between screens
+
+STEP 5: VERIFY
+  - Cross-check: every requirement has matching code
+  - Cross-check: every screen in doc has matching screen file
+  - Cross-check: every API endpoint has matching service method
+```
+
+## Quick Commands
+
+```
+"Read mockup.png and implement this screen"
+  → UI Analysis → Component tree → Generate code
+
+"Read requirements.pdf pages 1-10 and list all features"
+  → Requirements Extraction → Feature list
+
+"Read api.json and generate all models and services"
+  → Data Model Protocol → Types + Services
+
+"Read wireframe.png and create navigation flow"
+  → UI Analysis (focus on navigation) → Router setup
+
+"Read spec.docx and estimate feature scope"
+  → Requirements Extraction → Feature count + complexity
+```
+
+## Tips
+
+- **Large PDFs**: Always specify page range. Read table of contents first (page 1-2) to find relevant sections.
+- **Multiple mockups**: Read all screens first, identify shared components, create shared components first.
+- **API docs**: Generate types/models first, then services, then UI. Types are the foundation.
+- **Incomplete specs**: Flag missing information. Ask user before assuming.
+- **Conflicting info**: Document wins over assumption. If doc says X but code says Y, ask user which is correct.