@buivietphi/skill-mobile-mt 2.0.0 → 2.1.0

package/shared/prompt-engineering.md

@@ -1,6 +1,6 @@
 # Prompt Engineering — Intelligent Prompt Generation
 
-> Learned from Anthropic, Cline, Roo Code, and Claude Code.
+> Learned from Anthropic, Cursor, Lovable, Manus, Windsurf, Kiro, Claude Code, and top 50k+ star repos.
 > How to generate prompts that AI agents execute correctly.
 
 ---
@@ -64,40 +64,138 @@
 ```xml
 <think>
 BUG: [description]
-FILE: [path]
+ERROR MESSAGE: [paste exact error]
+
+⛔ STOP — CLASSIFY + SEARCH PROJECT FIRST (before ANY analysis):
+
+<error_classification>
+  TYPE: [RUNTIME CRASH / BUILD ERROR / TYPE MISMATCH / NETWORK ERROR /
+         RENDER ERROR / NAVIGATION ERROR / PERFORMANCE / STATE ERROR /
+         NATIVE ERROR / MEMORY ERROR / INVESTIGATION]
+
+  SEARCH STRATEGY based on type:
+  → RUNTIME/STATE/RENDER/NAVIGATION → Search src/ FIRST → then trace outward
+  → BUILD/NATIVE                    → Search config files FIRST (tsconfig/gradle/Pod/pubspec)
+  → NETWORK/API                     → Search API service files → then .env → then interceptors
+  → INVESTIGATION                   → Search by feature name → read → report (don't fix yet)
+
+  If complex bug → Read shared/debugging-intelligence.md for pattern match
+</error_classification>
+
+<project_search>
+  STEP 1: Extract keywords from error:
+  → File/path in stack trace: [extract]
+  → Function/class/component name: [extract]
+  → Module/package name: [extract]
+  → Line number: [extract if available]
+  → Error code / HTTP status: [extract if available]
+
+  STEP 2: Filter noise from log (if user pasted log):
+  → SKIP: node_modules/*, React internals, engine frames
+  → FOCUS: lines with src/ paths, "Error:", "Caused by:", YOUR component names
+
+  STEP 3: Search project source code (MANDATORY):
+  → Grep "[keyword]" src/             ← ALWAYS start here (unless BUILD error)
+  → Grep "[function_name]" src/       ← find the actual function
+  → Glob "**/*[ComponentName]*"       ← find the actual file
+  → Results: [list files found]
+
+  STEP 4: Read matched files (TOP 3-5):
+  → Read [file1] — [what I found: actual code, types, imports]
+  → Read [file2] — [what I found: related logic, callers]
+  → Read [file3] — [what I found: state/store connected to this]
+
+  ⛔ If I skipped Step 1-4 → GO BACK AND DO THEM NOW
+  ⛔ If I found 0 results in src/ → widen: lib/ → app/ → project root
+</project_search>
 
 <source_verification>
-  ⚠️ BEFORE analyzing — verify I have real data:
-  - [ ] Read the actual file (not guessing from error message)
-  - [ ] Verified function/class names exist (grep)
+  ⚠️ Verify I have REAL project data (not assumptions):
+  - [ ] Classified error type and picked correct search strategy
+  - [ ] Filtered noise from log (if applicable)
+  - [ ] Searched src/ with Grep for error keywords → found files
+  - [ ] Read the actual file(s) where bug occurs
+  - [ ] Verified function/class names exist in project (grep result)
   - [ ] Checked package versions in package.json/pubspec.yaml
   - [ ] Identified data types from actual code (not assumed)
+  - [ ] Traced the call chain: who calls this → what it returns
 </source_verification>
 
-<context_needed>
-  - Read [file] to understand current implementation
-  - Grep for similar patterns: grep "[pattern]" src/
-  - Check imports and dependencies
-</context_needed>
-
-<root_cause>
-  [Analyze AFTER loading context - don't guess]
-  - What code is executed?
-  - What values are passed?
-  - What conditions are checked?
-  SOURCE: [file:line where the bug is — cite exact location]
-</root_cause>
+<root_cause_tracing>
+  ⛔ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+
+  STEP 1 — IMMEDIATE CAUSE (what throws):
+  - Error type: [from classification above]
+  - Crash/error at: [file:line from project search]
+  - What code does at that line: [describe from reading]
+  - What value is wrong: [actual vs expected]
+
+  STEP 2 — TRACE BACKWARD (what called this):
+  - Who calls this function? → [grep callers in src/]
+  - What data does caller pass? → [trace data origin]
+  - Go up one level: who calls the caller? → [trace further]
+
+  STEP 3 — ROOT CAUSE (where chain breaks):
+  - Root cause at: [file:line — where correct data becomes incorrect]
+  - WHY it fails: [based on actual code read, NOT guess]
+  - Does this match a known pattern? → [check debugging-intelligence.md if loaded]
+  - Does root cause explain ALL symptoms? YES/NO
+    → If NO → theory is wrong → re-trace from Step 2
+</root_cause_tracing>
+
+<working_example>
+  Search for similar working code in SAME project:
+  → Grep for similar pattern that works: [search term]
+  → Found working example at: [file:line] (or "none found")
+  → Differences between broken vs working:
+    1. [difference]
+    2. [difference]
+  → The fix should align broken code with working pattern
+</working_example>
+
+<hypothesis>
+  ⛔ 1 HYPOTHESIS → 1 MINIMAL CHANGE → VERIFY
+
+  HYPOTHESIS: [specific theory based on root cause]
+  CHANGE: [smallest possible change to test this — 1 change only]
+  EXPECTED RESULT: [what should happen if hypothesis is correct]
+
+  ⛔ If this fails → REVERT → form NEW hypothesis (never stack fixes)
+  ⛔ If 3 hypotheses fail → STOP → question architecture
+</hypothesis>
 
 <fix>
-  [Specific change with code snippet]
+  [Specific change with code snippet — before → after]
 
   WHY IT WORKS:
-  [Explain the fix based on root cause]
+  [Explain based on root cause tracing — not guess]
   SOURCE: [where this fix pattern comes from — project code / skill file / official docs]
+
+  DEFENSE IN DEPTH (make bug structurally impossible):
+  - Layer 1 (input): [validation added]
+  - Layer 2 (state): [guard added]
+  - Layer 3 (render): [null check / fallback added]
 </fix>
 
+<verification>
+  ⛔ NO COMPLETION CLAIMS WITHOUT EVIDENCE
+
+  🚩 Anti-rationalization check:
+  - Am I saying "should work now" without running it? → RUN IT
+  - Am I "confident" without evidence? → PROVE IT
+  - Am I stacking 3+ changes? → REVERT. 1 change only.
+
+  Evidence:
+  - [ ] Fix addresses root cause (not just symptoms)
+  - [ ] All symptoms explained by this root cause
+  - [ ] Working example pattern followed (if found)
+  - [ ] Defense-in-depth added at [N] layers
+  - [ ] Side effects checked (grep for other callers)
+  - [ ] Both platforms considered (iOS + Android)
+</verification>
+
 <side_effects>
-  - Files that import this: [list after grep]
+  - Files that import this: [list from grep results]
   - Tests affected: [list]
   - Platform-specific: iOS [impact] / Android [impact]
 </side_effects>
@@ -116,6 +214,64 @@ FILE: [path]
 </think>
 ```
 
+### Diagnostic Scan (user unsure / vague / "check this for me")
+
+```xml
+<think>
+USER SAID: [what user described or asked — could be vague]
+AREA: [extract: screen name / feature name / module name / file name]
+
+<area_identification>
+  What did user mention or show?
+  → Screen/feature name: [extract from user's words]
+  → File pasted/referenced: [if any]
+  → Behavior described: [if any]
+  → If unclear → I should ask: "Which screen or feature should I check?"
+</area_identification>
+
+<project_search>
+  Search broadly for this area:
+  → Grep "[feature]" src/            → found: [list files]
+  → Glob "**/*[ScreenName]*"         → found: [list files]
+  → Also search: related hooks, services, stores, utils
+  → Total files to scan: [N files]
+</project_search>
+
+<diagnostic_scan>
+  For EACH file, run the checklist:
+
+  FILE: [file1:path]
+  □ Crash risks:    [findings or "clean"]
+  □ Memory leaks:   [findings or "clean"]
+  □ Race conditions: [findings or "clean"]
+  □ Security:       [findings or "clean"]
+  □ Performance:    [findings or "clean"]
+  □ UX/states:      [findings or "clean"]
+  □ Data flow:      [trace API → state → render — any break?]
+  □ Edge cases:     [empty data? error response? offline? slow?]
+
+  FILE: [file2:path]
+  □ ... (repeat for each file)
+</diagnostic_scan>
+
+<report>
+  Scanned: [N files] in [area name]
+
+  🔴 Issues found:
+    1. [SEVERITY] [file:line] — [description]
+    2. [SEVERITY] [file:line] — [description]
+
+  🟡 Suspicious (might be intentional):
+    1. [file:line] — [what looks off and why]
+
+  ✅ Looks good:
+    - [aspect that's well-implemented]
+
+  Recommendation: [what to fix first / what to investigate deeper]
+</report>
+</think>
+```
+
 **Example:**
 ```xml
 <think>
@@ -652,6 +808,101 @@ Faster than reading documentation.
 
 ---
 
+## Advanced Patterns (from top AI tools)
+
+### Verification-First Pattern (Anthropic #1 recommendation)
+
+```
+ALWAYS provide verification criteria BEFORE implementation:
+
+<good-example>
+  "Add pagination to ProductList. Verify: loads 20 items, next page
+   on scroll to bottom, shows loading spinner during fetch, handles
+   empty last page. Run: jest --testPathPattern=ProductList"
+</good-example>
+
+<bad-example>
+  "Add pagination to ProductList"
+  (no way to verify success)
+</bad-example>
+
+The single highest-leverage thing: include tests or expected outputs
+so the agent can check itself.
+```
+
+### Investigate-Before-Answer Pattern (used by Cursor, Lovable)
+
+```
+NEVER speculate about code you have not opened:
+
+STEP 1: User mentions file → Read it
+STEP 2: Understand the actual code → then answer
+STEP 3: If referencing a function → Grep to verify it exists
+
+⛔ "The error is probably because..." (guessing)
+✅ Read file → find line → "Line 42 accesses product.images[0]
+   without null check. The API sometimes returns empty array."
+```
+
+### Assumption-Driven Progress (from Cursor — for non-blocking work)
+
+```
+When NOT blocked but details are unclear:
+
+✅ State assumption clearly → proceed → let user correct
+  "Assuming REST API (matching product feature pattern). Creating
+   authService with axios. If this should use Firebase, let me know."
+
+⛔ Ask permission for every small decision
+  "Should I use axios or fetch? Should the file be named authService
+   or AuthService? Should I put it in services/ or api/?"
+```
+
+### Negative Space Pattern (used by ALL top tools)
+
+```
+Explicitly state what NOT to do — prevents drift:
+
+⛔ NEVER add new packages without checking existing deps first
+⛔ NEVER create utils/ or helpers/ for one-time operations
+⛔ NEVER add error handling for scenarios that can't happen
+⛔ NEVER refactor surrounding code when fixing a bug
+⛔ NEVER add comments to code that is self-explanatory
+```
+
+### Batched Operations (from Lovable — reduces tool call waste)
+
+```
+COMBINE operations that can run together:
+
+<good-example>
+  Read 3 files in ONE message (parallel):
+    Read src/features/product/ProductScreen.tsx
+    Read src/features/product/productService.ts
+    Read src/features/product/product.types.ts
+</good-example>
+
+<bad-example>
+  Read file 1 → wait → Read file 2 → wait → Read file 3
+  (3 round-trips instead of 1)
+</bad-example>
+```
+
+### Error Recovery with Escalation (from Cursor, Claude Code)
+
+```
+ATTEMPT 1: Auto-fix (missing imports, type errors, lint)
+ATTEMPT 2: Read related files, check dependencies
+ATTEMPT 3: Try alternative approach
+ATTEMPT 4: STOP → present options to user
+
+⛔ NEVER: loop on same error 5+ times
+⛔ NEVER: suppress errors to make tests pass
+✅ If corrected twice on same issue → /clear and restart with better prompt
+```
+
+---
+
 ## Quick Reference
 
 ### Good Prompt Checklist

package/shared/storage-patterns.md

@@ -0,0 +1,312 @@
+# Mobile Storage Patterns
+
+> On-device storage — when to use what, how to implement correctly.
+> Covers: AsyncStorage, MMKV, SecureStore/Keychain, SQLite, WatermelonDB, Realm, SharedPreferences.
+
+---
+
+## Decision Matrix — Pick Storage Type First
+
+```
+WHAT ARE YOU STORING?          → STORAGE TO USE
+────────────────────────────────────────────────────────────────────
+Auth tokens / secrets          → SecureStore (RN) / Keychain (iOS)
+                                 EncryptedSharedPreferences (Android)
+                                 flutter_secure_storage (Flutter)
+
+App preferences / settings     → MMKV (RN, fast KV)
+(theme, language, onboarding)    SharedPreferences (Android native)
+                                 UserDefaults (iOS native)
+                                 shared_preferences (Flutter)
+
+Simple key-value cache         → MMKV (RN) / MMKV (Flutter)
+(session data, small objects)
+
+Structured relational data     → SQLite (via expo-sqlite / sqflite)
+(offline CRUD, complex queries)  WatermelonDB (RN, reactive queries)
+                                 drift (Flutter, type-safe)
+
+Large offline datasets         → WatermelonDB (RN)
+(sync with server, observables)  drift (Flutter)
+                                 Room (Android native)
+                                 CoreData / SwiftData (iOS native)
+                                 Realm (cross-platform)
+
+Files / images / documents     → FileSystem (expo-file-system / path_provider)
+                                 AsyncStorage ❌ (NOT for binary data)
+
+⛔ RULE: AsyncStorage is deprecated for RN. Use MMKV instead.
+⛔ RULE: NEVER store tokens in AsyncStorage / SharedPreferences / UserDefaults.
+```
+
+---
+
+## React Native
+
+### 1. Secure Storage (Tokens, Credentials)
+
+```typescript
+// expo-secure-store (Expo) / react-native-keychain (bare RN)
+import * as SecureStore from 'expo-secure-store';
+
+// Store
+await SecureStore.setItemAsync('accessToken', token);
+
+// Read
+const token = await SecureStore.getItemAsync('accessToken');
+
+// Delete (on logout — ALWAYS do this)
+await SecureStore.deleteItemAsync('accessToken');
+await SecureStore.deleteItemAsync('refreshToken');
+
+// RULE: On logout, delete ALL secure store keys
+async function logout() {
+  await Promise.all([
+    SecureStore.deleteItemAsync('accessToken'),
+    SecureStore.deleteItemAsync('refreshToken'),
+    SecureStore.deleteItemAsync('userId'),
+  ]);
+}
+```
+
+### 2. MMKV (Preferences + KV Cache) — 60x faster than AsyncStorage
+
+```typescript
+// react-native-mmkv
+import { MMKV } from 'react-native-mmkv';
+
+// Create instance (one per app, or per domain)
+export const storage = new MMKV();
+
+// Typed wrapper (recommended)
+export const Storage = {
+  getString: (key: string) => storage.getString(key),
+  setString: (key: string, value: string) => storage.set(key, value),
+  getBoolean: (key: string) => storage.getBoolean(key) ?? false,
+  setBoolean: (key: string, value: boolean) => storage.set(key, value),
+  getObject: <T>(key: string): T | null => {
+    const raw = storage.getString(key);
+    return raw ? JSON.parse(raw) : null;
+  },
+  setObject: <T>(key: string, value: T) => storage.set(key, JSON.stringify(value)),
+  delete: (key: string) => storage.delete(key),
+  clear: () => storage.clearAll(),
+};
+
+// With Zustand persist (recommended combo)
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+
+const mmkvStorage = {
+  getItem: (name: string) => storage.getString(name) ?? null,
+  setItem: (name: string, value: string) => storage.set(name, value),
+  removeItem: (name: string) => storage.delete(name),
+};
+
+export const useSettingsStore = create(
+  persist(
+    (set) => ({
+      theme: 'light',
+      language: 'en',
+      setTheme: (theme: string) => set({ theme }),
+      setLanguage: (lang: string) => set({ language: lang }),
+    }),
+    { name: 'settings', storage: createJSONStorage(() => mmkvStorage) }
+  )
+);
+```
+
+### 3. SQLite / WatermelonDB (Structured Offline Data)
+
+```typescript
+// expo-sqlite (simple queries)
+import * as SQLite from 'expo-sqlite';
+
+const db = SQLite.openDatabaseSync('app.db');
+
+// Init schema
+db.execSync(`
+  CREATE TABLE IF NOT EXISTS tasks (
+    id TEXT PRIMARY KEY,
+    title TEXT NOT NULL,
+    completed INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL
+  )
+`);
+
+// Query
+const tasks = db.getAllSync<Task>('SELECT * FROM tasks WHERE completed = ?', [0]);
+
+// Insert
+db.runSync('INSERT INTO tasks (id, title, completed, created_at) VALUES (?, ?, ?, ?)',
+  [uuid(), 'Buy milk', 0, Date.now()]);
+```
+
+```typescript
+// WatermelonDB (reactive queries, sync-ready)
+// Best for: large datasets, reactive UI, server sync
+import { Database } from '@nozbe/watermelondb';
+import SQLiteAdapter from '@nozbe/watermelondb/adapters/sqlite';
+
+const adapter = new SQLiteAdapter({ schema, migrations });
+const database = new Database({ adapter, modelClasses: [Post, Comment] });
+
+// Observe (reactive — auto re-renders on change)
+const posts = database.get('posts').query().observe();
+```
+
+### 4. Avoid AsyncStorage (Legacy)
+
+```typescript
+// ❌ DEPRECATED — avoid in new projects
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+// ✅ Migrate to MMKV:
+// Before:  await AsyncStorage.setItem('theme', 'dark');
+// After:   storage.set('theme', 'dark');
+
+// ✅ Migrate to expo-secure-store for tokens:
+// Before:  await AsyncStorage.setItem('token', jwt);
+// After:   await SecureStore.setItemAsync('token', jwt);
+```
+
+---
+
+## Flutter
+
+### 1. Secure Storage (Tokens)
+
+```dart
+// flutter_secure_storage
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+
+final _secureStorage = FlutterSecureStorage(
+  aOptions: AndroidOptions(encryptedSharedPreferences: true),
+  iOptions: IOSOptions(accessibility: KeychainAccessibility.first_unlock),
+);
+
+// Store
+await _secureStorage.write(key: 'accessToken', value: token);
+
+// Read
+final token = await _secureStorage.read(key: 'accessToken');
+
+// Delete on logout
+await _secureStorage.deleteAll();
+```
+
+### 2. SharedPreferences / Hive (KV Storage)
+
+```dart
+// shared_preferences (simple, built-in)
+final prefs = await SharedPreferences.getInstance();
+await prefs.setString('language', 'en');
+final lang = prefs.getString('language') ?? 'en';
+
+// Hive (faster, type-safe, no codegen)
+import 'package:hive_flutter/hive_flutter.dart';
+
+await Hive.initFlutter();
+final box = await Hive.openBox('settings');
+box.put('theme', 'dark');
+final theme = box.get('theme', defaultValue: 'light');
+```
+
+### 3. Drift (SQLite, type-safe)
+
+```dart
+// drift — type-safe SQLite with code generation
+@DriftDatabase(tables: [Tasks])
+class AppDatabase extends _$AppDatabase {
+  AppDatabase() : super(_openConnection());
+
+  Stream<List<Task>> watchIncompleteTasks() =>
+    (select(tasks)..where((t) => t.completed.not())).watch();
+
+  Future insertTask(TasksCompanion task) => into(tasks).insert(task);
+}
+```
+
+---
+
+## iOS Native (Swift)
+
+```swift
+// UserDefaults — preferences ONLY (not tokens)
+UserDefaults.standard.set("en", forKey: "language")
+let lang = UserDefaults.standard.string(forKey: "language") ?? "en"
+
+// Keychain — tokens and secrets
+import Security
+
+func saveToKeychain(key: String, value: String) {
+    let data = value.data(using: .utf8)!
+    let query: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrAccount as String: key,
+        kSecValueData as String: data,
+        kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
+    ]
+    SecItemDelete(query as CFDictionary)
+    SecItemAdd(query as CFDictionary, nil)
+}
+
+// SwiftData / CoreData — structured offline data
+@Model class Task {
+    var id: UUID
+    var title: String
+    var completed: Bool
+    init(title: String) { self.id = UUID(); self.title = title; self.completed = false }
+}
+```
+
+---
+
+## Android Native (Kotlin)
+
+```kotlin
+// EncryptedSharedPreferences — tokens and secrets
+val masterKey = MasterKey.Builder(context)
+    .setKeyScheme(MasterKey.KeyScheme.AES256_GCM).build()
+val encryptedPrefs = EncryptedSharedPreferences.create(
+    context, "secure_prefs", masterKey,
+    EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+    EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
+)
+encryptedPrefs.edit().putString("accessToken", token).apply()
+
+// DataStore — preferences (replaces SharedPreferences)
+val Context.dataStore by preferencesDataStore(name = "settings")
+val LANGUAGE_KEY = stringPreferencesKey("language")
+
+suspend fun saveLanguage(context: Context, lang: String) {
+    context.dataStore.edit { it[LANGUAGE_KEY] = lang }
+}
+
+val languageFlow = context.dataStore.data.map { it[LANGUAGE_KEY] ?: "en" }
+
+// Room — structured offline data
+@Entity data class Task(@PrimaryKey val id: String, val title: String, val completed: Boolean)
+@Dao interface TaskDao {
+    @Query("SELECT * FROM task WHERE completed = 0") fun getActive(): Flow<List<Task>>
+    @Insert suspend fun insert(task: Task)
+}
+```
+
+---
+
+## Security Checklist
+
+```
+✅ Tokens → SecureStore / Keychain / EncryptedSharedPreferences ONLY
+✅ On logout → delete ALL secure storage keys
+✅ Encrypt sensitive data before storing in SQLite/MMKV
+✅ Don't log stored values (console.log, print)
+✅ Use device-only accessibility (not iCloud sync for tokens)
+
+⛔ NEVER: AsyncStorage for tokens
+⛔ NEVER: UserDefaults for tokens
+⛔ NEVER: SharedPreferences (unencrypted) for tokens
+⛔ NEVER: Log token values in debug output
+⛔ NEVER: Store plain-text passwords
+```