@buivietphi/skill-mobile-mt 2.0.1 → 2.2.0

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: skill-mobile-mt
 description: "Master Senior Mobile Engineer. Patterns from 30+ production repos (200k+ GitHub stars: Ignite, Expensify, Mattermost, Immich, AppFlowy, Now in Android, TCA). Use when: building mobile features, fixing mobile bugs, reviewing mobile code, mobile architecture, React Native, Flutter, iOS Swift, Android Kotlin, mobile performance, mobile security audit, mobile code review, app release. Two modes: (1) default = pre-built production patterns, (2) 'project' = reads current project and adapts."
-version: "2.0.0"
+version: "2.2.0"
 author: buivietphi
 priority: high
 user-invocable: true
@@ -50,25 +50,30 @@ RULE 7: ASK AFTER 3 FAILS — 3 failed attempts at same error → STOP → prese
 
 1. [Cardinal Rules](#cardinal-rules-inviolable)
 2. [Task Router](#task-router)
-3. [Communication Protocol](#communication-protocol)
-4. [Execution Modes](#execution-modes)
-5. [Mandatory Checkpoint](#mandatory-checkpoint)
-6. [Auto-Detect](#auto-detect)
-7. [Mobile Context](#mobile-context)
-8. [Mode Selection](#mode-selection)
-9. [Feature Scaffold Protocol](#feature-scaffold-protocol-project-mode)
-10. [Error Recovery Protocol](#error-recovery-protocol)
-11. [Quality Gate](#quality-gate)
-12. [Build & Deploy Gates](#build--deploy-gates)
-13. [Smart Loading](#smart-loading)
-14. [Grounding Protocol (Anti-Hallucination)](#grounding-protocol-anti-hallucination)
-15. [Docs-First Protocol (Always Use Latest)](#docs-first-protocol-always-use-latest)
-16. [Security Protocol](#security-protocol)
-17. [Hard Bans](#hard-bans)
-18. [Mobile Anti-Patterns](#mobile-anti-patterns)
-19. [Leverage Pyramid](#leverage-pyramid-where-to-invest-review-time)
-20. [Session State Tracking](#session-state-tracking-for-long-tasks)
-21. [Reference Files](#reference-files)
+3. [Intent Analysis Detector](#intent-analysis-detector-auto-load-sharedintent-analysismd) *(routes to shared/intent-analysis.md)*
+4. [Multi-Fix Execution Protocol](#multi-fix-execution-protocol)
+5. [UI Fix Protocol](#ui-fix-protocol)
+6. [Communication Protocol](#communication-protocol)
+7. [Decision Matrix Protocol](#decision-matrix-protocol)
+8. [Execution Modes](#execution-modes)
+9. [Mandatory Checkpoint](#mandatory-checkpoint)
+10. [Auto-Detect](#auto-detect)
+11. [Mobile Context](#mobile-context)
+12. [Mode Selection](#mode-selection)
+13. [Feature Scaffold Protocol](#feature-scaffold-protocol-project-mode)
+14. [Error Recovery Protocol](#error-recovery-protocol)
+15. [Quality Gate](#quality-gate) *(includes Completion Re-check)*
+16. [Build & Deploy Gates](#build--deploy-gates)
+17. [Codebase Scan Strategy](#codebase-scan-strategy)
+18. [Smart Loading](#smart-loading)
+19. [Grounding Protocol (Anti-Hallucination)](#grounding-protocol-anti-hallucination)
+20. [Docs-First Protocol (Always Use Latest)](#docs-first-protocol-always-use-latest)
+21. [Security Protocol](#security-protocol)
+22. [Hard Bans](#hard-bans)
+23. [Mobile Anti-Patterns](#mobile-anti-patterns)
+24. [Leverage Pyramid](#leverage-pyramid-where-to-invest-review-time)
+25. [Session State Tracking](#session-state-tracking-for-long-tasks)
+26. [Reference Files](#reference-files)
 
 ---
 
@@ -82,11 +87,18 @@ RULE 7: ASK AFTER 3 FAILS — 3 failed attempts at same error → STOP → prese
 ```
 USER REQUEST                    → ACTION (Read tool required)
 ─────────────────────────────────────────────────────────────────
-"Create/build X feature"        → Feature Scaffold Protocol below (no extra file needed)
+"Create/build X feature"        → Check: is the spec clear or vague?
+                                  CLEAR → Feature Scaffold Protocol (no extra file needed)
+                                  VAGUE → Spec Analysis Protocol FIRST → confirm → then scaffold
                                   screen + hook + service + store + types
 
-"Create/add X screen/page"      → Feature Scaffold Protocol below — MINIMAL
-                                  screen + hook ONLY (no service/store)
+"Create/add X screen/page"      → Check: is the spec clear or vague?
+                                  CLEAR → Feature Scaffold Protocol — MINIMAL (screen + hook)
+                                  VAGUE → Spec Analysis Protocol FIRST → confirm → then scaffold
+
+"Build something like X app /   → Read: shared/intent-analysis.md (Spec Analysis Protocol)
+ similar to / standard / usual /    Parse → classify → present structured spec → wait confirm
+ you know what I mean"              ⛔ NEVER start coding without confirmed spec
 
 "Add X to existing Y"           → MODIFY existing files, don't create new structure
 
@@ -94,12 +106,88 @@ USER REQUEST                    → ACTION (Read tool required)
                                   then: Read platform file (see Smart Loading below)
                                   then: suggest structure based on project size + stack
 
-"Fix / debug X"                 → Read: shared/bug-detection.md
-                                  then: read code → find root cause → fix → verify
+"Fix / debug X"                 → ⛔ STOP — DO NOT suggest anything yet
+                                  Step 1: CLASSIFY error type (crash/build/type/network/render/state/native)
+                                  Step 2: SEARCH PROJECT FIRST (mandatory before ANY suggestion)
+                                    → Grep error keywords in src/ (class name, function name, error message)
+                                    → Glob for related files (*.ts, *.tsx, *.dart, *.swift, *.kt)
+                                    → Read the TOP 3-5 matched files — understand actual code
+                                  Step 3: Find root cause IN PROJECT CODE (cite file:line)
+                                  Step 4: Fix → verify → cite source
+                                  ⛔ NEVER skip Step 1-2 — even if you "think" you know the answer
+                                  If complex/unfamiliar bug → also Read: shared/debugging-intelligence.md
+
+"Check issue / investigate X"   → ⛔ DO NOT FIX YET — investigate first
+                                  Step 1: Read issue description fully
+                                  Step 2: Extract affected feature + expected vs actual behavior
+                                  Step 3: Search project for affected code area (Grep/Glob src/)
+                                  Step 4: Read code → trace data flow → find root cause
+                                  Step 5: REPORT findings — ask user if they want a fix
+                                  ⛔ NEVER jump straight to fixing without reporting first
+
+"Paste error log / stack trace" → Step 1: FILTER noise (skip node_modules, engine frames)
+                                  Step 2: Extract signal lines (YOUR file paths, Error:, Caused by:)
+                                  Step 3: Parse stack trace by platform (RN/Flutter/iOS/Android)
+                                  Step 4: Search project src/ for extracted keywords
+                                  Step 5: Root cause → fix → cite
+                                  If long/complex trace → also Read: shared/debugging-intelligence.md
+
+"Take a look / something's off / → ⛔ USER DOESN'T KNOW THE CAUSE — run Diagnostic Scan:
+ not sure why / describe symptoms    Step 1: EXTRACT AREA from what user said or showed:
+ why / take a look / describe         → Screen name? Feature name? Module name? File name?
+ symptoms without error"              → If user paste code → that IS the area
+                                      → If user describe behavior → extract the feature/screen name
+                                    Step 2: SEARCH project for that area (mandatory):
+                                      → Grep "[feature/screen name]" src/
+                                      → Glob "**/*[name]*" to find all related files
+                                      → Read ALL matched files (not just 1 — scan broadly)
+                                    Step 3: RUN SCAN CHECKLIST on the code you just read:
+                                      → Walk through bug-detection.md Step 5 checklist
+                                      → Check: crash risks, memory leaks, race conditions,
+                                        security, performance, UX — against ACTUAL code
+                                    Step 4: REPORT what you found (structured):
+                                      → "I scanned [N files] in [area]."
+                                      → "Found [N] potential issues:" (list with severity + file:line)
+                                      → "No critical issues found." (if clean)
+                                      → "Suspicious: [describe what looks off based on code]"
+                                    Step 5: ASK what user wants to do:
+                                      → "Want me to fix [specific issue]?"
+                                      → "Want me to investigate [suspicious area] deeper?"
+                                    ⛔ NEVER say "I don't see any issues" without having searched
+                                    ⛔ NEVER suggest fixes before completing the scan report
+
+"Review" (generic, no scope)    → Read: shared/code-review.md → detect Review Mode:
+                                  → Check git status → if changes exist → MODE: CHANGES
+                                  → If no changes → ASK user: "Review full codebase or specific file?"
+
+"Review full code / audit"      → Read: shared/code-review.md → MODE: FULL
+                                  Read ALL src/ files → 12-category checklist → full report
+
+"Review changes / review diff"  → Read: shared/code-review.md → MODE: CHANGES
+                                  git diff → review only changed lines + context
+
+"Review file X / this file"     → Read: shared/code-review.md → MODE: FILE
+                                  Read specified file → 12-category checklist on that file
+
+"Review function X / this func" → Read: shared/code-review.md → MODE: FUNCTION
+                                  Find function → trace callers → deep review
+
+"Review PR / pull request"      → Read: shared/code-review.md → MODE: PR
+                                  Read: shared/anti-patterns.md
+                                  Step 0 PR-Level → git diff base..HEAD → 12-category → verdict
+
+"Review modified files"         → Read: shared/code-review.md → MODE: MODIFIED
+                                  git status → read modified files → review
+
+"Review commits"                → Read: shared/code-review.md → MODE: COMMITS
+                                  git log → git show each commit → review diffs
 
-"Review X / PR review"          → Read: shared/code-review.md
-                                  Read: shared/common-pitfalls.md
-                                  then: apply both checklists
+"Check PR"                      → Read: shared/code-review.md → MODE: PR-CHECK
+                                  Step 0 ONLY (size, scope, tests, commits) → quick ✅/🔴
+
+"Review accessibility / a11y"   → Read: shared/code-review.md (§ Accessibility)
+                                  then: WCAG 2.1 mobile checklist — labels, touch targets,
+                                  contrast, screen reader, font scaling, color, focus, motion
 
 "Optimize / performance X"      → Read: shared/bug-detection.md (§ Performance section)
                                   then: profile → identify bottleneck → fix
@@ -145,6 +233,17 @@ USER REQUEST                    → ACTION (Read tool required)
 "Offline / cache / sync"        → Read: shared/offline-first.md
                                   then: implement local-first architecture
 
+"Storage / lưu data / AsyncStorage / MMKV / SecureStore / Keychain /
+ SQLite / WatermelonDB / Realm / token storage / local database /
+ save to device / persist data"  → Read: shared/storage-patterns.md
+                                  then: pick storage type from matrix → implement → security check
+
+"i18n / multi-language / translation / localization / đa ngôn ngữ /
+ multilang / RTL / Arabic / locale / language switcher / date format /
+ number format / plural / slang / i18next / l10n" →
+                                  Read: shared/i18n-localization.md
+                                  then: pick library per platform → scaffold translations → RTL check
+
 "Write/run E2E tests"           → Read: shared/testing-strategy.md
                                   then: Detox (RN) or Maestro (cross-platform) or XCUITest/Espresso
 
@@ -160,6 +259,74 @@ USER REQUEST                    → ACTION (Read tool required)
 "Big feature / multi-screen"    → Read: shared/ai-dlc-workflow.md
                                   then: Elaborate → Construct (4 Hats) → Backpressure → Complete
 
+"Which is better / compare /     → Decision Matrix Protocol (in this file — no extra read)
+ nên dùng gì / best approach /     Present 2-3 options in matrix format → recommend → wait
+ options / trade-offs /             ⛔ NEVER just pick one without showing comparison
+ upgrade or not / migrate"
+
+"How much work / big change? /   → Estimation Protocol (in Decision Matrix Protocol section)
+ scope / effort / risk"            Scan → classify XS/S/M/L/XL → risk → present
+
+"Fix UI / match design /           → UI Fix Protocol (in this file)
+ adjust layout / UI broken /          Step 1: Identify what → Step 2: Read component tree
+ UI mismatch / layout wrong"          Step 3: Trace style chain → Step 4: Fix → Step 5: Verify
+
+"Fix multiple / fix A then B /    → Read: shared/intent-analysis.md (Task Extraction Protocol)
+ multiple files / fix + fix +        Extract ALL tasks → classify → order → track → verify ALL
+ fix UI + fix bug + add X"           ⛔ NEVER start until ALL tasks are listed
+
+"Update UI to match design /      → UI Fix Protocol (in this file)
+ Figma / screenshot / mockup"        Read component tree → trace style → fix → verify both themes
+
+"Make it better / improve this /  → Read: shared/intent-analysis.md (Scope Clarification Protocol)
+ fix everything / clean up /         Detect vague → clarify scope → set completion criteria
+ something is wrong / not right"     ⛔ NEVER start coding until scope is clear
+
+"It's slow / doesn't work /      → Read: shared/intent-analysis.md (Intent Understanding Protocol)
+ button doesn't work / blank /       Map non-technical → technical → search code → fix
+ freezes / flickers / keeps          Confirm interpretation before acting
+ crashing / shows old data"
+
+"Fix that / same for this one /   → Read: shared/intent-analysis.md (Context Tracking)
+ the other screen / do it again /    Resolve pronoun → confirm reference → proceed
+ like before / undo that"            ⛔ NEVER guess when reference is ambiguous
+
+"URGENT / production down /       → Read: shared/intent-analysis.md (Priority Detection)
+ before release / deadline /         Adjust depth: CRITICAL=fix only, HIGH=fix+verify
+ blocker / ASAP"                     Skip nice-to-haves, communicate progress
+
+"Build feature from spec /        → Read: shared/spec-to-code.md
+ implement from requirements /       Parse → dependency graph → file plan → types-first → implement
+ convert spec to code"              ⛔ NEVER skip type definitions
+
+"Setup state management /         → Read: shared/code-generation-templates.md
+ add Zustand / Redux / Riverpod /    Production templates with persist, middleware, selectors
+ setup API client / setup forms /    API client with retry + token refresh + error normalization
+ form validation"                    Forms with Zod, multi-step, file upload
+
+"Add navigation / auth flow /     → Read: shared/navigation-patterns.md
+ deep links / modal / tabs /         Auth stack, deep link config, modal groups, tab persistence
+ push notifications /                Push notification setup + deep link from notification
+ permissions"                        Permission request + denied handling + settings redirect
+
+"Carousel / swipe / gestures /    → Read: shared/complex-ui-patterns.md
+ responsive / tablet / keyboard /    Image carousel, swipe cards, gesture handling
+ dark mode / skeleton /              Responsive layout, keyboard avoidance, dark mode theme
+ accessibility / a11y"              Skeleton loading, accessibility implementation per platform
+
+"Pagination / infinite scroll /   → Read: shared/data-flow-patterns.md
+ optimistic update / cache /         Cursor + offset pagination, prefetching
+ real-time / WebSocket /             Optimistic updates with rollback, cache invalidation
+ offline queue"                      WebSocket manager, offline request queue
+
+"Error handling / retry /         → Read: shared/error-handling.md
+ error boundary / toast /            Error type hierarchy, user-facing messages
+ global error handler"              Error boundary, retry with backoff, toast notifications
+
+"Write unit tests / component     → Read: shared/testing-patterns.md
+ tests / mock / factory /            Component tests (4 states), hook tests, service tests
+ test setup / test helpers"          Test factories, provider wrapper, snapshot strategy
+
 ```
 
 **⛔ NEVER start coding without identifying the task type first.**
@@ -167,6 +334,185 @@ USER REQUEST                    → ACTION (Read tool required)
 
 ---
 
+## Intent Analysis Detector (auto-load shared/intent-analysis.md)
+
+**BEFORE coding: detect if input needs deep analysis. If yes → Read shared/intent-analysis.md.**
+
+```
+═══ COMPLEXITY SIGNALS — auto-trigger Read: shared/intent-analysis.md ═══
+
+MULTI-PART → Task Extraction Protocol:
+  - Multiple sentences with different requests
+  - Comma-separated requests ("fix A, fix B, add C")
+  - References to multiple files/screens/components
+  ⛔ NEVER start coding after reading only the first sentence
+
+VAGUE INPUT → Scope Clarification Protocol:
+  - "Make it better / fix the UI / improve this / fix everything"
+  - No specific screen, component, or symptom mentioned
+  ⛔ NEVER guess what "better" means — clarify first
+
+NON-TECHNICAL → Intent Understanding Protocol:
+  - "Button doesn't work / screen is blank / it freezes / takes forever"
+  - Map everyday language → technical cause → search code → fix
+  ⛔ NEVER ask user for error message if they clearly don't have one
+
+CONTEXT REFERENCE → Intent Understanding Protocol — Context Tracking:
+  - "Fix that / same for this one / the other screen / like before"
+  - Resolve pronoun → confirm reference → proceed
+  ⛔ NEVER guess when reference is ambiguous
+
+URGENCY → Intent Understanding Protocol — Priority Detection:
+  - CRITICAL: "URGENT / production down / users affected"
+  - HIGH: "before release / deadline / blocker"
+  - LOW: "when you get a chance / not urgent / nice to have"
+
+VAGUE FEATURE → Spec Analysis Protocol:
+  - "Build X like other apps / something similar to Y / you know what I mean"
+  - Present ✅/❓/⚠️ structured spec → wait confirm → then build
+  ⛔ NEVER start building from a vague description
+
+CLEAR INPUT (skip — proceed to Task Router directly):
+  - "Fix the login button — it doesn't respond to tap"
+  - "Add loading spinner to ProfileScreen"
+  - Single task with specific target + action
+```
+
+---
+
+## Multi-Fix Execution Protocol
+
+**When fixing multiple issues across multiple files:**
+
+```
+⛔ DO NOT edit 5 files then check if it works.
+✅ Fix → Verify → Fix → Verify → Fix → Verify (incremental)
+
+═══ EXECUTION FLOW ═══
+
+PHASE 1: MAP (before any edit)
+  → Read ALL affected files first (parallel reads)
+  → Map dependencies: "File A imports from File B"
+  → Identify shared code: "Both Screen X and Screen Y use useAuth"
+  → Decide order: edit shared/base code FIRST, then consumers
+
+PHASE 2: EXECUTE (one fix at a time)
+  For each task (in dependency order):
+    1. STATE what you're fixing: "Fixing TASK 2: crash on back press"
+    2. READ the target file(s) — even if read before (Context Staleness Rule)
+    3. EDIT — make the change
+    4. VERIFY — check imports resolve, types pass, no new errors
+    5. MARK complete: "✅ TASK 2 done"
+    6. CHECK SIDE EFFECTS: did this change break anything else?
+       → If yes → fix the side effect BEFORE moving to next task
+
+PHASE 3: FINAL VERIFICATION
+  → Re-read ALL modified files
+  → Run Quality Gate on each
+  → Verify no circular breakage (File A fix didn't break File B fix)
+  → List all changes: "Modified: FileA.tsx (line 45), FileB.tsx (line 12, 89)"
+
+═══ SIDE EFFECTS MAP ═══
+
+When editing a file, CHECK these for side effects:
+  SHARED HOOK changed?     → Re-check ALL screens that use it
+  NAVIGATION changed?      → Re-check ALL screens that navigate to/from it
+  TYPE/INTERFACE changed?   → Re-check ALL files that import it
+  API SERVICE changed?      → Re-check ALL hooks/screens that call it
+  STYLE/THEME changed?      → Re-check ALL components using that style
+  STATE SHAPE changed?      → Re-check ALL selectors/consumers
+
+═══ CONFLICT DETECTION ═══
+
+Before editing a file that was already edited in this session:
+  → RE-READ the file (your earlier edit is already applied)
+  → Verify your new edit doesn't revert the previous fix
+  → If conflict: merge both fixes into one coherent edit
+```
+
+---
+
+## UI Fix Protocol
+
+**When user asks to fix UI / match design / adjust layout:**
+
+```
+⛔ DO NOT guess what the UI should look like.
+✅ READ the actual component code first.
+✅ TRACE the style chain: component → stylesheet → theme → platform.
+
+═══ UI FIX WORKFLOW ═══
+
+STEP 1: IDENTIFY what needs fixing
+  → User says "fix UI" → ASK: "Which screen/component? What's wrong specifically?"
+  → User shows screenshot → Compare with code structure
+  → User references design → Read the design spec/figma description
+
+STEP 2: READ the component tree (top-down)
+  → Screen file (the container)
+  → Child components used in that screen
+  → Shared components (Button, Input, Card, etc.)
+  → Style files / theme files
+  → DO NOT skip any layer — UI bugs often come from parent, not child
+
+STEP 3: TRACE the style chain
+  For each UI element to fix:
+    → Inline style? → check the style object
+    → StyleSheet? → find the stylesheet, check the exact rule
+    → Theme? → check if theme variable is correct
+    → Platform-specific? → check Platform.OS / platform files
+    → Responsive? → check Dimensions / useWindowDimensions
+    → Dark mode? → check if both light/dark have the value
+
+STEP 4: FIX with precision
+  → Edit ONLY the specific style/layout property
+  → DO NOT refactor the entire component "while you're at it"
+  → Preserve existing patterns (if project uses StyleSheet, don't switch to inline)
+
+STEP 5: VERIFY the fix
+  → Re-read the component → does the fix make visual sense?
+  → Check sibling components → are they still consistent?
+  → Check platform: if RN → both iOS and Android affected?
+  → Check theme: if dark mode exists → fix applies to both themes?
+
+═══ COMMON UI FIX PATTERNS ═══
+
+SPACING/ALIGNMENT:
+  → Check: padding, margin, flex, alignItems, justifyContent
+  → Common mistake: mixing padding on parent AND child → double spacing
+  → Fix: adjust ONE layer, not both
+
+TEXT NOT SHOWING / CUT OFF:
+  → Check: numberOfLines, flex: 1, width, overflow
+  → Common mistake: parent has fixed height → child text truncated
+  → Fix: use flexShrink/flexGrow or remove fixed height
+
+IMAGE WRONG SIZE:
+  → Check: resizeMode, width/height, aspectRatio
+  → Common mistake: no explicit dimensions → image takes natural size
+  → Fix: set explicit width + aspectRatio (not width + height)
+
+LIST PERFORMANCE:
+  → Check: FlatList vs ScrollView, keyExtractor, getItemLayout
+  → Common mistake: ScrollView with 100+ items → jank
+  → Fix: switch to FlatList + add keyExtractor + getItemLayout if fixed height
+
+KEYBOARD OVERLAP:
+  → Check: KeyboardAvoidingView, behavior (iOS=padding, Android=height)
+  → Common mistake: no KeyboardAvoidingView → input hidden behind keyboard
+  → Fix: wrap in KeyboardAvoidingView with correct behavior per platform
+
+═══ MULTI-SCREEN UI FIX ═══
+
+When fixing UI across multiple screens:
+  → FIX shared components FIRST (Button, Header, Input, etc.)
+  → Then fix individual screens (they inherit from shared)
+  → Verify consistency: same Button should look same on all screens
+  → Check navigation transitions: screen A → screen B still smooth?
+```
+
+---
+
 ## Communication Protocol
 
 **Show progress, not monologues. Brief status updates before each tool use.**
@@ -219,6 +565,130 @@ BAD:
 
 ---
 
+## Decision Matrix Protocol
+
+**When multiple valid approaches exist, ALWAYS present a structured comparison — NEVER just pick one.**
+
+### When This Triggers
+
+```
+TRIGGERS:
+  - User asks "how should I..." / "what's the best way to..."
+  - Multiple libraries/tools can solve the same problem
+  - Architecture decisions (monolith vs modular, REST vs GraphQL, etc.)
+  - Migration/upgrade questions ("should I upgrade to X?")
+  - Trade-off situations (performance vs simplicity, native vs cross-platform)
+  - User says "give me options" / "what are my choices"
+
+⛔ DO NOT just pick one approach and implement it
+✅ Present comparison → let user decide → then implement
+```
+
+### Decision Matrix Format
+
+```
+STEP 1: RESEARCH (before presenting options)
+  → Read project code to understand constraints
+  → Check existing patterns (what does the project already use?)
+  → WebSearch for latest recommendations + benchmarks
+  → Identify 2-3 viable options (no more — too many = analysis paralysis)
+
+STEP 2: PRESENT MATRIX
+
+  ┌────────────────────────────────────────────────────────────┐
+  │ DECISION: [What we're deciding]                            │
+  │ CONTEXT: [Project constraints — framework, SDK, team size] │
+  ├──────────────┬──────────────┬──────────────┬───────────────┤
+  │              │ Option A     │ Option B     │ Option C      │
+  ├──────────────┼──────────────┼──────────────┼───────────────┤
+  │ What         │ [1 sentence] │ [1 sentence] │ [1 sentence]  │
+  │ Pros         │ • fast       │ • simple     │ • scalable    │
+  │              │ • typed      │ • small      │ • official    │
+  │ Cons         │ • complex    │ • no types   │ • heavy       │
+  │ Performance  │ [fast/med/slow]│ [fast/med/slow]│ [fast/med/slow]│
+  │ Bundle Size  │ [small/med/large]│ [small/med/large]│ [small/med/large]│
+  │ Learning     │ [easy/med/hard]│ [easy/med/hard]│ [easy/med/hard]│
+  │ Maintenance  │ [low/med/high]│ [low/med/high]│ [low/med/high]│
+  │ Community    │ [stars/npm weekly]│ [stars/npm weekly]│ [stars/npm weekly]│
+  │ Fits Project │ ✅/⚠️/❌     │ ✅/⚠️/❌     │ ✅/⚠️/❌     │
+  └──────────────┴──────────────┴──────────────┴───────────────┘
+
+STEP 3: RECOMMENDATION (with reasoning)
+  → "I recommend Option [X] because:
+     1. [reason based on project code — cite file]
+     2. [reason based on constraints]
+     3. [reason based on trade-offs]"
+  → "However, Option [Y] is better if [condition]."
+
+STEP 4: WAIT FOR USER DECISION
+  → ⛔ DO NOT implement until user picks
+  → If user says "just pick one" → implement your recommendation
+```
+
+### Estimation Protocol (for scope/effort questions)
+
+```
+When user asks "how much work is this?" / "is this a big change?" / "should we do X?":
+
+STEP 1: SCAN SCOPE
+  → Glob + Grep to count affected files
+  → Identify: how many files change? how many new files?
+  → Check: any breaking changes to existing features?
+
+STEP 2: CLASSIFY EFFORT
+  ┌──────────────────────────────────────────────────┐
+  │ XS  │ 1-2 files │ Simple change, no side effects │
+  │ S   │ 3-5 files │ Contained change, few deps      │
+  │ M   │ 6-15 files│ Cross-feature, some testing      │
+  │ L   │ 16+ files │ Architectural, needs planning    │
+  │ XL  │ 30+ files │ Major refactor, phased approach   │
+  └──────────────────────────────────────────────────┘
+
+STEP 3: RISK ASSESSMENT
+  → Breaking changes: [none / minor / major]
+  → Test coverage: [good / partial / none — need to add]
+  → Rollback difficulty: [easy / medium / hard]
+  → Dependencies affected: [list them]
+
+STEP 4: PRESENT
+  "This is a [S/M/L] change:
+   → [N] files to modify, [N] new files
+   → Risk: [low/medium/high] — [why]
+   → Suggestion: [do it now / plan first / phase it]"
+```
+
+### Migration/Upgrade Decision Protocol
+
+```
+When user asks "should I upgrade to X?" / "migrate from A to B?":
+
+STEP 1: CHECK CURRENT STATE
+  → Read package.json / pubspec.yaml → exact current versions
+  → Grep for deprecated APIs currently used in src/
+  → Count how many files use the library/API being upgraded
+
+STEP 2: CHECK TARGET STATE
+  → WebSearch "[library] migration guide [current version] to [target version]"
+  → WebSearch "[library] breaking changes [target version]"
+  → List ALL breaking changes that affect THIS project
+
+STEP 3: IMPACT ANALYSIS
+  → For each breaking change → Grep in src/ → count affected files
+  → Classify: auto-fixable (codemod) vs manual fix
+
+STEP 4: PRESENT DECISION
+  "Upgrading [X] from [v1] to [v2]:
+   → Breaking changes: [N] that affect your project
+   → Files to update: [N]
+   → Auto-fixable: [N] (via codemod)
+   → Manual fixes: [N]
+   → Risk: [low/medium/high]
+   → Recommendation: [upgrade now / wait / partial upgrade]
+   → If upgrading: [suggest phased plan]"
+```
+
+---
+
 ## Execution Modes
 
 **Switch modes based on task phase. Each mode has different behavior.**
@@ -568,28 +1038,47 @@ file upload / camera →
 ```
 ERROR ENCOUNTERED → RECOVERY FLOW:
 
-ATTEMPT 1: Auto-fix obvious issues
-  - Missing imports? → Add them
-  - Type errors? → Fix types
+⛔ BEFORE ANY ATTEMPT: Search project source code first
+  → Grep error keywords in src/ (file name, function name, class name)
+  → Read matched files to understand actual code context
+  → ONLY THEN proceed to fix attempts
+
+ATTEMPT 1: Fix based on project code analysis
+  - You already searched src/ → you know WHERE the issue is
+  - Missing imports? → Check what the file actually imports → add correct one
+  - Type errors? → Read the actual types/interfaces in project → fix to match
   - Linter errors? → Auto-format
   - Run verification → success? DONE : next attempt
 
-ATTEMPT 2: Deeper investigation
-  - Read related files
-  - Check dependencies installed
+ATTEMPT 2: Widen search — read related files
+  - Grep for the function/class across entire project (not just src/)
+  - Read files that CALL or IMPORT the broken code
+  - Check dependencies installed (package.json / pubspec.yaml)
   - Verify native module linked (mobile)
   - Run verification → success? DONE : next attempt
 
-ATTEMPT 3: Alternative approach
-  - Try different solution
-  - Use fallback library
-  - Simplify implementation
+ATTEMPT 3: Alternative approach (still based on project context)
+  - Look at how SIMILAR features are implemented in the project
+  - Clone working pattern → adapt for this case
+  - Simplify implementation if needed
   - Run verification → success? DONE : next attempt
 
-ATTEMPT 4: STOP & ASK USER
-  - Describe what failed
-  - Show 3 attempts made
-  - Present 2-3 options
+⚠️ 3 FAILS = QUESTION ARCHITECTURE (mandatory checkpoint):
+  If 3 attempts failed on the SAME error → STOP fixing and ask:
+  - "Is this the right approach entirely?"
+  - "Is the underlying pattern/architecture wrong?"
+  - "Should I be solving a DIFFERENT problem?"
+  Search project for working alternatives:
+  → Grep for similar feature that WORKS → compare the patterns
+  → The bug may not be a bug — it may be a wrong approach
+
+ATTEMPT 4: STOP & ASK USER (with evidence)
+  - Show what you searched and found in project
+  - Show EACH attempt: what you tried + what happened + why it failed
+  - ⛔ NEVER say "I tried everything" — show EXACTLY what you tried
+  - If 3+ fails: "This suggests the issue may be architectural.
+    I found [working_pattern] in [file] that solves this differently."
+  - Present 2-3 options with trade-offs
   - Wait for user decision
 ```
 
@@ -656,9 +1145,41 @@ STEP 2: REVIEW — Re-read your own code with fresh eyes:
   - Would a senior dev approve this in code review?
   - Am I importing anything that doesn't exist in the project?
 STEP 3: REFINE — Fix issues found in review
-STEP 4: VERIFY — Run Quality Gate above → all pass? → DONE
+STEP 4: VERIFY — Run Quality Gate above → all pass?
+STEP 5: COMPLETION RE-CHECK (MANDATORY — never skip)
+  → Re-read the user's ORIGINAL message (scroll up if needed)
+  → List every task/request the user made
+  → For EACH task, verify:
+    □ Was it actually done? (not just planned, actually EDITED)
+    □ Which file:line was changed?
+    □ Does the change match what user asked?
+  → If ANY task was missed → DO IT NOW before saying "done"
+  → Report:
+    "✅ Done. Changes:"
+    "1. [task] → [file:line] — [what changed]"
+    "2. [task] → [file:line] — [what changed]"
 
 If STEP 2 finds issues → loop back to STEP 3 (max 2 loops)
+If STEP 5 finds missed tasks → loop back to STEP 1 for those tasks
+```
+
+### Common "Forgot to Complete" Patterns
+
+```
+⛔ PATTERN 1: "I'll do that next" → then never does it
+  → FIX: Track with Task Extraction Protocol, check off each task
+
+⛔ PATTERN 2: Read the file, understand the issue, but forgot to EDIT
+  → FIX: After each task, verify you actually USED the Edit/Write tool
+
+⛔ PATTERN 3: Fixed file A, but file B also needed the same fix
+  → FIX: After fixing, Grep for same pattern in other files
+
+⛔ PATTERN 4: Fixed the logic but forgot to update the UI/types/tests
+  → FIX: Side Effects Map (see Multi-Fix Execution Protocol)
+
+⛔ PATTERN 5: User said "fix multiple places" but AI fixed only the first one
+  → FIX: Task Extraction Protocol → extract ALL → track ALL → verify ALL
 ```
 
 ### Context Staleness Rule
@@ -795,6 +1316,118 @@ FOR UI CHANGES:
 
 ---
 
+## Codebase Scan Strategy
+
+**Protocol for large projects, monorepos, and multi-module codebases. Choose the right scan depth.**
+
+### When This Triggers
+
+```
+TRIGGERS:
+  - Project has > 50 files in src/
+  - Monorepo with multiple apps/packages
+  - Multi-module project (app/ + packages/ + shared/)
+  - User says "new project" / "first time seeing this code"
+  - User says "check the whole codebase" / "audit"
+  - You don't know where to start
+
+⛔ DO NOT Read every file — token waste
+⛔ DO NOT guess structure from folder names alone
+✅ Scan strategically: breadth first, depth on demand
+```
+
+### Scan Levels
+
+```
+LEVEL 1: QUICK SCAN (~5 reads) — for focused tasks
+  ┌─────────────────────────────────────────────────────────┐
+  │ 1. ls src/ (or app/ or lib/) → map top-level folders    │
+  │ 2. Read package.json / pubspec.yaml → deps + scripts    │
+  │ 3. Read 1 config file (tsconfig / eslint / analysis)    │
+  │ 4. Read CLAUDE.md / README.md (if exists)               │
+  │ 5. Glob "**/*[feature_name]*" → find target files       │
+  │                                                         │
+  │ USE WHEN: Task is focused (fix bug, add to existing)    │
+  └─────────────────────────────────────────────────────────┘
+
+LEVEL 2: STANDARD SCAN (~15 reads) — for new features
+  ┌─────────────────────────────────────────────────────────┐
+  │ Everything in Level 1 PLUS:                             │
+  │ 6. ls each top-level src/ subfolder → map full tree     │
+  │ 7. Read 1 screen file (UI pattern)                      │
+  │ 8. Read 1 service/api file (data pattern)               │
+  │ 9. Read 1 hook/viewmodel file (state pattern)           │
+  │ 10. Read 1 store/slice file (state management)          │
+  │ 11. Read navigation/router config                       │
+  │ 12. Read .env.example (if exists) → API endpoints       │
+  │ 13. Grep "TODO\|FIXME\|HACK" src/ → known issues       │
+  │ 14. Read types/models directory → data shapes           │
+  │ 15. Read test file (if exists) → testing patterns       │
+  │                                                         │
+  │ USE WHEN: Building new feature, need full context       │
+  └─────────────────────────────────────────────────────────┘
+
+LEVEL 3: DEEP SCAN (~30+ reads) — for audits & architecture
+  ┌─────────────────────────────────────────────────────────┐
+  │ Everything in Level 2 PLUS:                             │
+  │ 16. Read ALL screen/page files (list them all)          │
+  │ 17. Read ALL service/api files                          │
+  │ 18. Read ALL store/state files                          │
+  │ 19. Map dependency graph: who imports whom              │
+  │ 20. Check circular imports                              │
+  │ 21. Read native config (ios/Info.plist, AndroidManifest)│
+  │ 22. Read CI/CD config (if exists)                       │
+  │ 23. Read ALL test files                                 │
+  │ 24. Grep for security issues (hardcoded keys, tokens)   │
+  │ 25+. Read shared/common components                      │
+  │                                                         │
+  │ USE WHEN: Full audit, architecture review, migration    │
+  └─────────────────────────────────────────────────────────┘
+```
+
+### Monorepo Strategy
+
+```
+MONOREPO DETECTED WHEN:
+  → Root has packages/ or apps/ or modules/ or workspaces in package.json
+  → Multiple package.json files at different levels
+  → lerna.json / nx.json / turbo.json exists
+
+SCAN PROTOCOL FOR MONOREPOS:
+  1. READ ROOT: package.json → workspaces field → list all packages
+  2. MAP PACKAGES: ls packages/ (or apps/) → list each package
+  3. IDENTIFY TARGET: Which package does the user's task affect?
+  4. FOCUS: Scan ONLY the target package at Level 2
+  5. SHARED: Also scan shared packages that target imports
+     → Grep "from ['\"](../../packages|@monorepo)" in target package
+  6. IGNORE: Other packages unless explicitly asked
+
+  ⛔ NEVER scan the entire monorepo — scan the target package
+  ✅ Treat each package as its own project with its own scan
+```
+
+### Multi-Module Strategy (React Native + Native)
+
+```
+MULTI-MODULE DETECTED WHEN:
+  → Project has src/ (JS/TS) + ios/ + android/ folders
+  → Native modules exist (react-native.config.js or manual linking)
+  → Custom native code beyond standard template
+
+SCAN PROTOCOL:
+  1. IDENTIFY LAYER: Is the task JS/TS-only or involves native?
+  2. JS/TS TASK → Scan src/ only (Level 1 or 2)
+  3. NATIVE TASK → Also scan:
+     → ios/[AppName]/ → Swift/ObjC source files
+     → android/app/src/main/java/ → Kotlin/Java source files
+     → Check bridging: ios/[AppName]-Bridging-Header.h
+     → Check native modules: Grep "RCT_EXPORT_MODULE" or "@ReactMethod"
+  4. CROSS-LAYER TASK (JS calls native) → Scan both layers
+     → Find the bridge: NativeModules.X in JS → X module in native
+```
+
+---
+
 ## Smart Loading
 
 **After auto-detect, use the Read tool to open ONLY relevant files.**
@@ -818,6 +1451,17 @@ FOR UI CHANGES:
 | All platforms | `shared/platform-excellence.md` | 🟡 Task Router says so |
 | All platforms | `shared/version-management.md` | 🟡 Task Router says so |
 | All platforms | `shared/observability.md` | 🟡 Task Router says so |
+| All platforms | `shared/storage-patterns.md` | 🟡 Task Router says so |
+| All platforms | `shared/i18n-localization.md` | 🟡 Task Router says so |
+| All platforms | `shared/debugging-intelligence.md` | 🟡 Complex bugs / stack traces / issue investigation |
+| All platforms | `shared/intent-analysis.md` | 🟡 Multi-part, vague, non-technical, or ambiguous input |
+| All platforms | `shared/code-generation-templates.md` | 🟡 State management, API client, forms setup |
+| All platforms | `shared/spec-to-code.md` | 🟡 Building feature from spec/requirements |
+| All platforms | `shared/navigation-patterns.md` | 🟡 Auth flow, deep links, modals, tabs, permissions |
+| All platforms | `shared/complex-ui-patterns.md` | 🟡 Carousel, gestures, responsive, dark mode, a11y |
+| All platforms | `shared/data-flow-patterns.md` | 🟡 Pagination, optimistic updates, cache, WebSocket |
+| All platforms | `shared/error-handling.md` | 🟡 Error hierarchy, retry, error boundary, toast |
+| All platforms | `shared/testing-patterns.md` | 🟡 Component tests, hook tests, factories, snapshots |
 
 **Cross-platform:** Flutter/RN projects also Read `ios/ios-native.md` + `android/android-native.md` for native modules.
 
@@ -899,19 +1543,80 @@ RULE 6: NO PHANTOM PACKAGES
 ### When Fixing Bugs
 
 ```
-GROUNDED BUG FIX PROTOCOL:
-
-1. READ the file with the bug (don't guess from error message alone)
-2. FIND the exact line causing the issue
-3. UNDERSTAND the data flow (what calls this? what does it return?)
-4. VERIFY the fix works with the actual types/interfaces in the project
-5. CHECK side effects (grep for other files using this function)
-6. CITE: "Fix in [file]:[line] — [root cause] — [why fix works]"
-
-⛔ NEVER:
+GROUNDED BUG FIX PROTOCOL (NON-NEGOTIABLE):
+
+⛔ BEFORE YOU SAY ANYTHING — SEARCH THE PROJECT FIRST:
+
+STEP 0: EXTRACT KEYWORDS + CHECK GIT (mandatory)
+  → Parse error message for: file name, function name, class name, module name, line number
+  → If error says "Cannot find X" → Grep for "X" in src/
+  → If error says "TypeError in Y" → Grep for "Y" in src/
+  → If error says "Module not found: Z" → Grep for "Z" in package.json AND src/
+  → CHECK RECENT CHANGES (if git project):
+    → First: git rev-parse --is-inside-work-tree 2>/dev/null
+    → If NOT git / no commits → skip git check → go to Step 1
+    → If git: git log --oneline -5 + git diff HEAD~3 --name-only
+    → If broken file was recently changed → read that diff FIRST
+    → 80%+ of bugs are caused by recent changes
+
+STEP 1: SEARCH PROJECT SOURCE (mandatory — NEVER skip)
+  → Grep: search error keywords in src/ directory FIRST
+  → Glob: find related files by pattern (*.ts, *.tsx, *.dart, *.swift, *.kt)
+  → Read: open the TOP 3-5 most relevant matched files
+  → If no match in src/ → search in lib/, app/, packages/, modules/
+  → If STILL no match → expand to project root
+
+STEP 2: READ & UNDERSTAND actual code
+  → Read the file(s) found in Step 1
+  → Trace the data flow: what calls this? what does it return?
+  → Check imports, types, interfaces IN THE PROJECT
+  → Check package.json / pubspec.yaml for dependency versions
+
+STEP 3: FIND ROOT CAUSE in project code
+  → Cite exact file:line where the bug originates
+  → Explain WHY it fails based on the actual code you just read
+
+STEP 4: FIND WORKING EXAMPLE (before fixing)
+  → Search SAME project for similar code that WORKS
+  → Compare broken code vs working code → list differences
+  → The fix should make broken code match the working pattern
+  → If no working example → proceed to Step 5
+
+STEP 5: SINGLE HYPOTHESIS FIX
+  → Form ONE hypothesis from root cause
+  → Make the SMALLEST possible change
+  → ⛔ NEVER stack multiple fixes at once
+  → ⛔ NEVER "fix it and also refactor nearby code"
+  → Verify: does this fix ALL symptoms?
+  → If no → REVERT → new hypothesis (don't carry failed fixes forward)
+
+STEP 6: DEFENSE IN DEPTH (after fix verified)
+  → Add validation at every layer data passes through
+  → Make the bug structurally impossible to recur
+  → Grep for side effects (other files using this function)
+
+STEP 7: CITE source with evidence
+  → "Root cause: [file]:[line] — [what's wrong] — [traced from Step 2-3]"
+  → "Working example: [file]:[line] — [how it works correctly]"
+  → "Fix: [change] — [why it works] — [defense added at layers X, Y]"
+
+⛔ HARD VIOLATIONS (auto-fail):
+  - Suggesting a fix WITHOUT first running Grep/Glob on the project
   - "The error is probably because..." (guess without reading code)
   - "Try changing X to Y" (without reading the file first)
   - "This should fix it" (without verifying types match)
+  - Suggesting generic Stack Overflow solutions without checking project context
+  - Jumping to package.json/config fixes before checking src/ code
+  - Stacking 3+ changes at once (1 hypothesis → 1 change → verify)
+  - Claiming "done" without fresh verification evidence
+  - "Should work now" / "I'm confident" without running/reading output
+
+🚩 ANTI-RATIONALIZATION (catch yourself):
+  "Should work now"           → You didn't verify. RUN IT.
+  "I'm confident this fixes"  → Confidence ≠ evidence. PROVE IT.
+  "Probably a race condition" → Buzzword. TRACE the async flow.
+  "Let me also clean up..."   → STOP. Fix the bug only.
+  Same fix 3+ times          → Architecture problem. STOP & rethink.
 ```
 
 ### Anti-Hallucination Checklist (run before EVERY response)
@@ -1527,6 +2232,9 @@ skill-mobile-mt/
     ├── platform-excellence.md        ← 🟡 iOS 18+ vs Android 15+ guidelines
     ├── version-management.md         ← 🟡 SDK compatibility matrix
     ├── observability.md              ← 🟡 Sessions as 4th pillar
+    ├── offline-first.md              ← 🟢 Local-first + sync patterns
+    ├── storage-patterns.md           ← 🟡 MMKV / SecureStore / SQLite / WatermelonDB / Keychain
+    ├── i18n-localization.md          ← 🟡 i18next / slang / .xcstrings / strings.xml / RTL
     │
-    └── offline-first.md              ← 🟢 Local-first + sync patterns
+    └── debugging-intelligence.md     ← 🟡 30+ error patterns + search strategies + issue investigation
 ```