@buivietphi/skill-mobile-mt 2.0.1 → 2.2.0

package/shared/navigation-patterns.md

@@ -0,0 +1,375 @@
+# Navigation Patterns — Complex Flows
+
+> On-demand module. Loaded when implementing auth flows, deep links, modals, or tab navigation.
+> Contains production patterns for React Native, Flutter, iOS, and Android.
+
+---
+
+## Auth-Based Navigation Flow
+
+### React Native (React Navigation)
+
+```typescript
+// navigation/RootNavigator.tsx
+import { NavigationContainer } from '@react-navigation/native';
+import { createNativeStackNavigator } from '@react-navigation/native-stack';
+import { useAuthStore, useIsLoggedIn } from '@/stores/useAuthStore';
+
+const Stack = createNativeStackNavigator<RootStackParamList>();
+
+export function RootNavigator() {
+  const isLoggedIn = useIsLoggedIn();
+  const [isReady, setIsReady] = useState(false);
+
+  useEffect(() => {
+    // Check stored token on app start
+    async function bootstrap() {
+      const hasToken = useAuthStore.getState().token;
+      if (hasToken) {
+        const valid = await useAuthStore.getState().refreshSession();
+        if (!valid) useAuthStore.getState().logout();
+      }
+      setIsReady(true);
+    }
+    bootstrap();
+  }, []);
+
+  if (!isReady) return <SplashScreen />;
+
+  return (
+    <NavigationContainer>
+      <Stack.Navigator screenOptions={{ headerShown: false }}>
+        {isLoggedIn ? (
+          // Authenticated stack
+          <>
+            <Stack.Screen name="MainTabs" component={MainTabNavigator} />
+            <Stack.Screen name="ProductDetail" component={ProductDetailScreen} />
+            <Stack.Screen name="Settings" component={SettingsScreen} />
+            {/* Modals */}
+            <Stack.Group screenOptions={{ presentation: 'modal' }}>
+              <Stack.Screen name="EditProfile" component={EditProfileScreen} />
+              <Stack.Screen name="ImageViewer" component={ImageViewerScreen} />
+            </Stack.Group>
+          </>
+        ) : (
+          // Unauthenticated stack
+          <>
+            <Stack.Screen name="Onboarding" component={OnboardingScreen} />
+            <Stack.Screen name="Login" component={LoginScreen} />
+            <Stack.Screen name="Register" component={RegisterScreen} />
+            <Stack.Screen name="ForgotPassword" component={ForgotPasswordScreen} />
+          </>
+        )}
+      </Stack.Navigator>
+    </NavigationContainer>
+  );
+}
+```
+
+### Flutter (GoRouter)
+
+```dart
+// navigation/app_router.dart
+import 'package:go_router/go_router.dart';
+
+final appRouter = GoRouter(
+  initialLocation: '/',
+  redirect: (context, state) {
+    final isLoggedIn = ref.read(authProvider).isLoggedIn;
+    final isAuthRoute = state.matchedLocation.startsWith('/auth');
+
+    if (!isLoggedIn && !isAuthRoute) return '/auth/login';
+    if (isLoggedIn && isAuthRoute) return '/';
+    return null;
+  },
+  routes: [
+    // Auth routes
+    GoRoute(path: '/auth/login', builder: (_, __) => const LoginScreen()),
+    GoRoute(path: '/auth/register', builder: (_, __) => const RegisterScreen()),
+
+    // App routes with bottom nav shell
+    ShellRoute(
+      builder: (_, __, child) => ScaffoldWithNavBar(child: child),
+      routes: [
+        GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
+        GoRoute(path: '/search', builder: (_, __) => const SearchScreen()),
+        GoRoute(path: '/cart', builder: (_, __) => const CartScreen()),
+        GoRoute(path: '/profile', builder: (_, __) => const ProfileScreen()),
+      ],
+    ),
+
+    // Detail routes (no bottom nav)
+    GoRoute(
+      path: '/product/:id',
+      builder: (_, state) => ProductDetailScreen(id: state.pathParameters['id']!),
+    ),
+  ],
+);
+```
+
+---
+
+## Deep Linking
+
+### React Native (Expo Router)
+
+```typescript
+// app/_layout.tsx — Expo Router handles deep links automatically via file structure
+// URL: myapp://product/abc-123 → app/product/[id].tsx
+
+// app/product/[id].tsx
+import { useLocalSearchParams } from 'expo-router';
+
+export default function ProductDetailScreen() {
+  const { id } = useLocalSearchParams<{ id: string }>();
+
+  // Validate param exists
+  if (!id) return <NotFoundScreen />;
+
+  // Fetch and render
+  const { data, isLoading } = useProductDetail(id as ProductId);
+  // ...
+}
+```
+
+### React Navigation Deep Link Config
+
+```typescript
+// navigation/linking.ts
+const linking: LinkingOptions<RootStackParamList> = {
+  prefixes: ['myapp://', 'https://myapp.com'],
+  config: {
+    screens: {
+      MainTabs: {
+        screens: {
+          Home: 'home',
+          Profile: 'profile/:userId',
+        },
+      },
+      ProductDetail: 'product/:productId',
+      Settings: 'settings',
+    },
+  },
+};
+
+// Handle notification deep links
+import * as Notifications from 'expo-notifications';
+
+function useNotificationDeepLink() {
+  const navigation = useAppNavigation();
+
+  useEffect(() => {
+    const sub = Notifications.addNotificationResponseReceivedListener(response => {
+      const data = response.notification.request.content.data;
+      if (data.screen === 'ProductDetail' && data.productId) {
+        navigation.navigate('ProductDetail', { productId: data.productId as ProductId });
+      }
+    });
+    return () => sub.remove();
+  }, [navigation]);
+}
+```
+
+---
+
+## Bottom Tab Navigation
+
+### React Native — Lazy Tabs with State Preservation
+
+```typescript
+// navigation/MainTabNavigator.tsx
+import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
+
+const Tab = createBottomTabNavigator<MainTabParamList>();
+
+export function MainTabNavigator() {
+  return (
+    <Tab.Navigator
+      screenOptions={{
+        headerShown: false,
+        // Lazy load: render tab only when first visited
+        lazy: true,
+        // Freeze inactive tabs (prevent re-renders)
+        freezeOnBlur: true,
+        tabBarActiveTintColor: theme.colors.primary,
+      }}
+    >
+      <Tab.Screen
+        name="Home"
+        component={HomeScreen}
+        options={{
+          tabBarIcon: ({ color, size }) => <HomeIcon color={color} size={size} />,
+          tabBarLabel: 'Home',
+        }}
+      />
+      <Tab.Screen
+        name="Search"
+        component={SearchScreen}
+        options={{
+          tabBarIcon: ({ color, size }) => <SearchIcon color={color} size={size} />,
+        }}
+      />
+      <Tab.Screen
+        name="Cart"
+        component={CartScreen}
+        options={{
+          tabBarIcon: ({ color, size }) => <CartIcon color={color} size={size} />,
+          tabBarBadge: cartCount > 0 ? cartCount : undefined,
+        }}
+      />
+      <Tab.Screen
+        name="Profile"
+        component={ProfileScreen}
+        options={{
+          tabBarIcon: ({ color, size }) => <ProfileIcon color={color} size={size} />,
+        }}
+      />
+    </Tab.Navigator>
+  );
+}
+```
+
+---
+
+## Modal Navigation
+
+### React Native — Modal Stack
+
+```typescript
+// Present as modal (slides up from bottom on iOS)
+navigation.navigate('EditProfile'); // registered in modal group
+
+// Dismiss modal
+navigation.goBack();
+
+// Modal with result — pass callback via params or use event
+// Option A: Use navigation params
+navigation.navigate('SelectAddress', {
+  onSelect: (address: Address) => {
+    // handle selected address
+  },
+});
+
+// Option B: Use event emitter
+import { DeviceEventEmitter } from 'react-native';
+// In modal: DeviceEventEmitter.emit('addressSelected', address);
+// In parent: DeviceEventEmitter.addListener('addressSelected', handler);
+```
+
+### Flutter — Modal Bottom Sheet
+
+```dart
+// Modal bottom sheet
+showModalBottomSheet(
+  context: context,
+  isScrollControlled: true, // full-height if needed
+  useSafeArea: true,
+  builder: (context) => DraggableScrollableSheet(
+    initialChildSize: 0.6,
+    minChildSize: 0.3,
+    maxChildSize: 0.9,
+    builder: (_, controller) => AddressPickerSheet(scrollController: controller),
+  ),
+);
+```
+
+---
+
+## Push Notification Navigation
+
+### React Native (Expo Notifications)
+
+```typescript
+// hooks/useNotificationSetup.ts
+import * as Notifications from 'expo-notifications';
+import * as Device from 'expo-device';
+
+export function useNotificationSetup() {
+  useEffect(() => {
+    registerForPush();
+  }, []);
+
+  async function registerForPush() {
+    if (!Device.isDevice) return; // skip simulator
+
+    const { status } = await Notifications.getPermissionsAsync();
+    let finalStatus = status;
+
+    if (status !== 'granted') {
+      const { status: newStatus } = await Notifications.requestPermissionsAsync();
+      finalStatus = newStatus;
+    }
+
+    if (finalStatus !== 'granted') return;
+
+    const token = (await Notifications.getExpoPushTokenAsync()).data;
+    await userService.registerPushToken(token);
+  }
+}
+
+// Notification handler — runs when app receives notification
+Notifications.setNotificationHandler({
+  handleNotification: async () => ({
+    shouldShowAlert: true,
+    shouldPlaySound: true,
+    shouldSetBadge: true,
+  }),
+});
+```
+
+---
+
+## Permissions Handling Pattern
+
+```typescript
+// hooks/usePermission.ts
+import * as Location from 'expo-location';
+import * as Camera from 'expo-camera';
+import { Alert, Linking } from 'react-native';
+
+type PermissionType = 'camera' | 'location' | 'notifications';
+
+export function usePermission(type: PermissionType) {
+  const [granted, setGranted] = useState<boolean | null>(null);
+
+  const request = useCallback(async () => {
+    let result: { status: string };
+
+    switch (type) {
+      case 'camera':
+        result = await Camera.requestCameraPermissionsAsync();
+        break;
+      case 'location':
+        result = await Location.requestForegroundPermissionsAsync();
+        break;
+      case 'notifications':
+        result = await Notifications.requestPermissionsAsync();
+        break;
+    }
+
+    if (result.status === 'granted') {
+      setGranted(true);
+      return true;
+    }
+
+    // Permission denied — guide user to settings
+    Alert.alert(
+      'Permission Required',
+      `Please enable ${type} access in Settings to use this feature.`,
+      [
+        { text: 'Cancel', style: 'cancel' },
+        { text: 'Open Settings', onPress: () => Linking.openSettings() },
+      ]
+    );
+    setGranted(false);
+    return false;
+  }, [type]);
+
+  return { granted, request };
+}
+
+// Usage:
+// const camera = usePermission('camera');
+// const canUse = await camera.request();
+// if (canUse) { /* proceed */ }
+```

package/shared/prompt-engineering.md

@@ -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>