@haposoft/cafekit 0.16.0-rc.7 → 0.16.0

package/src/claude/skills/mobile-development/references/mobile-mindset.md

@@ -1,542 +0,0 @@
-# Mobile Development Mindset & Thinking Patterns
-
-Essential thinking patterns and decision-making frameworks for successful mobile development.
-
-## The 10 Commandments of Mobile Development
-
-### 1. Performance is Foundation, Not Feature
-- **Reality**: Users may abandon apps when load time exceeds 3s
-- **Mindset**: Optimize from day one, not "later"
-- **Action**: Set performance budgets before writing code
-
-### 2. Every Kilobyte, Every Millisecond Matters
-- **Reality**: Mobile = constrained environment (battery, memory, network)
-- **Mindset**: Desktop assumptions don't apply
-- **Action**: Profile real devices, not simulators
-
-### 3. Offline-First by Default
-- **Reality**: Network is unreliable (elevators, tunnels, airplanes, poor signal)
-- **Mindset**: Design for offline, sync when online
-- **Action**: Local persistence first, cloud sync second
-
-### 4. User Context > Developer Environment
-- **Reality**: Users on trains, walking, one-handed, bright sunlight
-- **Mindset**: Test in real-world scenarios
-- **Action**: Real device testing mandatory
-
-### 5. Platform Awareness Without Platform Lock-In
-- **Reality**: iOS and Android users expect different patterns
-- **Mindset**: Respect conventions, but keep logic portable
-- **Action**: Platform-specific UI, shared business logic
-
-### 6. Iterate, Don't Perfect (2024-2025 Survival Strategy)
-- **Reality**: Mobile landscape changes rapidly
-- **Mindset**: Ship, measure, improve cycle
-- **Action**: MVP → User feedback → Iterate
-
-### 7. Security and Accessibility by Design
-- **Reality**: Not afterthoughts, but core requirements
-- **Mindset**: Build trust and inclusivity from start
-- **Action**: Security audit + accessibility testing in every sprint
-
-### 8. Test on Real Devices
-- **Reality**: Simulators lie about performance, battery, network
-- **Mindset**: Simulators for speed, devices for truth
-- **Action**: CI/CD with real device farms
-
-### 9. Architecture Scales with Complexity
-- **Reality**: Over-engineering kills simple apps
-- **Mindset**: Start simple, refactor when needed
-- **Action**: MVVM for small apps, Clean Architecture when complexity demands
-
-### 10. Continuous Learning is Survival
-- **Reality**: AI tools are widely used by developers (2024), frameworks evolve constantly
-- **Mindset**: Embrace change, allocate learning time
-- **Action**: 1+ hour weekly for new tech/patterns
-
-## Mobile-Specific Constraints & Thinking
-
-### Small Screens (Constraint → Design Parameter)
-
-**Constraint:**
-- 5-7 inch screens, thumb-reach zones, fat finger problem
-
-**Thinking Shift:**
-- Embrace minimalism: "What can we remove?"
-- Priority-based hierarchy: Most important action front and center
-- Progressive disclosure: Hide complexity behind layers
-
-**Practical Targets:**
-- 44x44px minimum touch targets (iOS)
-- 48x48px minimum touch targets (Android)
-- Primary actions within thumb reach (bottom 1/3)
-- Maximum 3-4 items in bottom navigation
-
-**Example Decision:**
-```
-❌ Bad: 8-column data table on mobile
-✅ Good: Card view with 3 key metrics, "View more" for details
-```
-
-### Limited Resources (Every KB/ms Matters)
-
-**Constraint:**
-- Battery drain, memory pressure, thermal throttling
-
-**Thinking Shift:**
-- Resource consciousness in every decision
-- Measure before optimizing (don't guess)
-- Graceful degradation on low-end devices
-
-**Practical Targets:**
-- <100MB memory for typical screens
-- <5% battery drain per hour active use
-- <50MB initial download, <200MB total
-- 60 FPS (16.67ms per frame)
-
-**Example Decision:**
-```
-❌ Bad: Load all 1000 items in list
-✅ Good: Virtualized list (10 items visible + buffer)
-```
-
-### Intermittent Connectivity (Offline-First)
-
-**Constraint:**
-- Network unreliable: elevators, tunnels, poor signal, airplane mode
-
-**Thinking Shift:**
-- Local-first data architecture
-- Optimistic UI updates
-- Sync conflict resolution strategy
-
-**Practical Approaches:**
-- **Write-through cache**: Write local, sync background
-- **Hybrid sync**: Push (realtime) + Pull (periodic)
-- **Conflict resolution**: Last-write-wins with timestamps or CRDT
-
-**Example Decision:**
-```
-❌ Bad: Show spinner while posting comment
-✅ Good: Show comment immediately (optimistic), sync background, handle conflicts
-```
-
-## Platform-Specific Thinking
-
-### iOS Mental Model
-
-**Philosophy**: Consistent, polished, opinionated
-- Users expect iOS patterns (tab bar, navigation bar, swipe back)
-- Design reviews reject non-standard UIs
-- "It just works" expectation = zero tolerance for crashes
-
-**Fragmentation**: LOW
-- Most users on iOS 16+ (2024)
-- Only ~50 device models to test
-- Predictable hardware specs
-
-**Design Thinking**:
-- Follow Human Interface Guidelines religiously
-- Native navigation patterns non-negotiable
-- Haptic feedback for important actions
-- Respect safe areas (notch, Dynamic Island)
-
-**When to Go Native iOS:**
-- App Store is primary revenue channel
-- Need latest Apple features (WidgetKit, Live Activities)
-- Target affluent user base (iOS users spend 2.5x more)
-
-### Android Mental Model
-
-**Philosophy**: Flexible, customizable, democratic
-- Users expect Material Design but tolerate variations
-- Extreme fragmentation = defensive programming
-- "Back button" = fundamental navigation expectation
-
-**Fragmentation**: HIGH
-- 24,000+ device models
-- Android 6-14 in active use (8 years of OS versions)
-- Wide range of hardware specs (512MB to 12GB RAM)
-
-**Design Thinking**:
-- Material Design 3 as baseline
-- Test on low-end devices (1GB RAM minimum)
-- Respect system navigation (gesture vs 3-button)
-- Handle back button properly
-
-**When to Go Native Android:**
-- Global market focus (Android dominates)
-- Emerging markets (Android dominates)
-- Enterprise/B2B (customization needs)
-
-## Performance Mindset (Every Millisecond Matters)
-
-### Critical Metrics (User Perception)
-
-| Metric | Threshold | User Perception |
-|--------|-----------|-----------------|
-| **Launch time** | <2s | Acceptable |
-| **Launch time** | 2-3s | Noticeable delay |
-| **Launch time** | >3s | Users may abandon |
-| **Screen load** | <1s | Instant (cached) |
-| **Screen load** | 1-3s | Acceptable (network) |
-| **Screen load** | >3s | Frustrating |
-| **Animation** | 60 FPS | Smooth |
-| **Animation** | 30-60 FPS | Noticeable jank |
-| **Animation** | <30 FPS | Unusable |
-
-### Performance Budget Example
-
-**Mobile App Performance Budget:**
-```
-Launch Time
-├─ Cold start: <2s (target 1.5s)
-├─ Warm start: <1s
-└─ Hot start: <0.5s
-
-Screen Load
-├─ Cached data: <500ms
-├─ Network data: <2s
-└─ Heavy computation: <3s
-
-Memory
-├─ Typical screen: <100MB
-├─ Heavy screen (images): <150MB
-└─ Peak usage: <200MB
-
-Network
-├─ Initial bundle: <2MB
-├─ Per screen: <500KB
-└─ Images: <200KB each
-
-Battery
-├─ Active use: <5% per hour
-├─ Background: <1% per hour
-└─ Idle: <0.1% per hour
-```
-
-### Optimization Decision Tree
-
-**Is it slow?**
-1. **Measure first** (Xcode Instruments, Android Profiler)
-2. **Find bottleneck** (CPU, memory, network, disk I/O)
-3. **Fix biggest impact** (80/20 rule)
-4. **Measure again** (verify improvement)
-
-**Common Culprits:**
-- Synchronous main thread operations
-- Unoptimized images (too large, wrong format)
-- N+1 query problem (fetch in loop)
-- Memory leaks (retain cycles, listeners)
-- Re-renders without memoization
-
-## Mobile Development Workflow
-
-### Iterative Development Cycle (Agile)
-
-**Sprint Structure (2 weeks):**
-```
-Week 1: Build + Test
-├─ Day 1-2: Design + plan
-├─ Day 3-4: Implement core
-└─ Day 5: Code review + tests
-
-Week 2: Polish + Ship
-├─ Day 6-7: Bug fixes + polish
-├─ Day 8: QA testing
-├─ Day 9: Staging deployment
-└─ Day 10: Production release (staged)
-```
-
-**Daily Workflow:**
-1. Pull latest code
-2. Run tests locally
-3. Develop feature/fix
-4. Write/update tests
-5. Local testing on device
-6. Code review
-7. CI/CD validation
-8. Merge to develop
-
-**CI/CD Impact:**
-- Faster development and deployment with fewer production bugs
-
-### Common Pitfalls & Avoidance
-
-#### 1. Testing Only on Simulators
-**Problem**: Simulators don't show real performance (battery, memory, network)
-**Solution**: Real device testing mandatory before every release
-**Impact**: Some bugs only appear on real devices
-
-#### 2. Ignoring Platform Conventions
-**Problem**: Custom navigation confuses users
-**Solution**: Follow iOS HIG and Material Design
-**Impact**: Non-standard UIs can lower engagement
-
-#### 3. No Offline Handling
-**Problem**: Network failures = blank screens, errors
-**Solution**: Offline-first architecture, cached data
-**Impact**: Users can experience network issues daily
-
-#### 4. Poor Memory Management
-**Problem**: Memory leaks → crashes, poor performance
-**Solution**: ARC/GC understanding, profile regularly
-**Impact**: Memory issues are a leading crash cause
-
-#### 5. Hardcoded Credentials
-**Problem**: Security vulnerability, API key exposure
-**Solution**: Environment variables, secure storage
-**Impact**: Apps can leak sensitive data; follow OWASP guidance.
-
-#### 6. No Accessibility
-**Problem**: Excludes users with disabilities or situational needs
-**Solution**: VoiceOver/TalkBack testing, semantic labels
-**Impact**: Accessibility = 1.3B global market
-
-#### 7. Premature Optimization
-**Problem**: Wasted time optimizing non-bottlenecks
-**Solution**: Measure first, optimize biggest impact
-**Impact**: Many performance issues come from a small part of the code
-
-#### 8. Over-Engineering
-**Problem**: Complex architecture for simple apps
-**Solution**: Start simple, scale when needed
-**Impact**: 3x longer development for no user benefit
-
-#### 9. Skipping Real Device Testing
-**Problem**: Missed battery drain, thermal issues
-**Solution**: Device farm in CI/CD, manual testing
-**Impact**: Some performance issues are device-specific
-
-#### 10. Not Respecting Battery
-**Problem**: Background processing drains battery
-**Solution**: Batch operations, respect Doze Mode
-**Impact**: Battery drain = #1 uninstall reason
-
-## Debugging Strategies & Tools (2024-2025)
-
-### iOS Debugging (Xcode 16)
-
-**Tools:**
-- **Instruments**: Profiling (Time, Allocations, Leaks, Network)
-- **Memory Graph**: Visual retain cycles
-- **View Hierarchy**: UI debugging
-- **Network Link Conditioner**: Simulate poor network
-- **Console**: System logs, os_log
-
-**AI-Driven:**
-- Xcode 16 AI crash analysis
-- Automatic memory leak detection
-- Performance suggestions
-
-**Process:**
-1. Reproduce bug on device
-2. Attach debugger / capture crash log
-3. Symbolicate crash report
-4. Fix root cause (not symptom)
-5. Add test to prevent regression
-
-### Android Debugging (Android Studio Giraffe+)
-
-**Tools:**
-- **Profiler**: CPU, Memory, Network, Energy
-- **Layout Inspector**: 3D view hierarchy
-- **Database Inspector**: SQLite/Room debugging
-- **Network Inspector**: API call monitoring
-- **Logcat**: System logs with filters
-
-**AI-Driven:**
-- Android Vitals: Crash clustering, ANR analysis
-- Firebase Crashlytics: AI-powered issue grouping
-- Play Console insights: User-reported bugs
-
-**Process:**
-1. Reproduce on emulator/device
-2. Check Logcat for stack traces
-3. Use Android Profiler for performance
-4. Fix and verify with instrumented tests
-5. Monitor Play Console vitals post-release
-
-### Cross-Platform Debugging
-
-**React Native:**
-- Chrome DevTools / Safari Web Inspector
-- Flipper (meta debugger: network, layout, logs)
-- Reactotron (state inspection)
-
-**Flutter:**
-- Flutter DevTools (Inspector, Timeline, Memory, Network)
-- Dart Observatory (VM debugging)
-- Widget Inspector (UI debugging)
-
-## Progressive Enhancement & Graceful Degradation
-
-### Progressive Enhancement (Build Up)
-
-**Strategy**: Start with baseline, enhance for capable devices
-
-**Example: Image Loading**
-```
-Baseline (all devices):
-├─ Show placeholder immediately
-├─ Load low-res image (10KB)
-└─ Display with smooth fade-in
-
-Enhancement (modern devices):
-├─ Check network (fast = high-res)
-├─ Check memory (ample = cache)
-└─ Progressive JPEG rendering
-```
-
-**Benefits:**
-- Works on all devices
-- Optimal experience on modern devices
-- No user left behind
-
-### Graceful Degradation (Strip Down)
-
-**Strategy**: Build for best, degrade for constraints
-
-**Example: Animation**
-```
-Best (flagship devices):
-├─ Complex particle effects
-├─ 120 FPS animations
-└─ Parallax scrolling
-
-Degraded (budget devices):
-├─ Simple fade transitions
-├─ 60 FPS target
-└─ Disable parallax (GPU load)
-```
-
-**Detection:**
-```javascript
-// React Native
-const isLowEndDevice =
-  DeviceInfo.getTotalMemory() < 2000000000; // <2GB
-
-if (isLowEndDevice) {
-  // Disable heavy animations
-  // Reduce concurrent operations
-  // Lower image quality
-}
-```
-
-**Benefits:**
-- Optimized for all hardware tiers
-- Prevents crashes on low-end devices
-- Better user experience across spectrum
-
-## Native vs Cross-Platform Decision Framework
-
-### Decision Tree
-
-**Q1: Do you need 100% native performance?**
-- **Yes** → Native (Swift/Kotlin)
-- **No** → Continue
-
-**Q2: Is team comfortable with JavaScript?**
-- **Yes** → React Native
-- **No** → Continue
-
-**Q3: Need desktop or web versions too?**
-- **Yes** → Flutter
-- **No** → Continue
-
-**Q4: Complex animations or custom UI?**
-- **Yes** → Flutter
-- **No** → React Native (easier for standard UIs)
-
-**Q5: Existing codebase to share?**
-- **React web app** → React Native
-- **No existing code** → Flutter (cleaner slate)
-
-### Hybrid Approach (Best of Both Worlds)
-
-**Strategy**: Cross-platform for most features, native for critical paths
-
-**Example Architecture:**
-```
-React Native / Flutter
-├─ UI and business logic
-├─ Standard features
-└─ API integration
-
-Native Modules
-├─ Performance-critical (video processing)
-├─ Platform-specific (HealthKit, Android Auto)
-└─ Third-party SDKs (payment, analytics)
-```
-
-**When to Use:**
-- Best: Leverage cross-platform speed + native power
-- Complexity: Maintain native module knowledge
-- Team: Need both cross-platform and native developers
-
-## Architecture Decision-Making
-
-### Complexity-Based Architecture Selection
-
-**Simple App (1-5 screens, basic CRUD)**
-- **Architecture**: MVVM (no Clean Architecture)
-- **State**: Local state (useState, setState)
-- **Reasoning**: Over-engineering adds complexity without benefit
-
-**Medium App (5-20 screens, moderate logic)**
-- **Architecture**: MVVM with clear separation
-- **State**: Global state management (Zustand, Riverpod)
-- **Reasoning**: Scalability without over-engineering
-
-**Complex App (20+ screens, enterprise logic)**
-- **Architecture**: Clean Architecture (domain, data, presentation)
-- **State**: Advanced state management + dependency injection
-- **Reasoning**: Maintainability and testability critical
-
-### Architecture Evolution
-
-**Start Simple:**
-```
-v1.0: MVVM, local state, single module
-└─ Focus: Ship fast, validate idea
-
-v2.0: Add global state when needed
-└─ Trigger: Props drilling becomes painful
-
-v3.0: Add Clean Architecture when scaling
-└─ Trigger: Team grows, features multiply
-
-v4.0: Extract microservices if justified
-└─ Trigger: Independent deployment needs
-```
-
-**Key Principle:** Refactor when pain > refactoring cost, not before
-
-## Resources & Continuous Learning
-
-**Weekly Learning Targets (2024-2025):**
-- 1 hour: New framework features
-- 30 min: Performance optimization techniques
-- 30 min: Security updates (CVEs, OWASP)
-- 30 min: Community articles/videos
-
-**Top Resources:**
-- iOS: Apple WWDC videos, Swift by Sundell
-- Android: Android Dev Summit, Medium Android Dev
-- React Native: React Native Blog, Expo Blog
-- Flutter: Flutter Engage, Medium Flutter
-- Mobile DevOps: Bitrise Blog, Fastlane guides
-
-**Communities:**
-- Stack Overflow (mobile tags)
-- Reddit (r/iOSProgramming, r/androiddev, r/reactnative, r/FlutterDev)
-- Discord (React Native, Flutter official)
-- Twitter: Follow framework creators and contributors
-
-**AI Tools (widely adopted in 2024):**
-- GitHub Copilot: Code completion, boilerplate
-- ChatGPT/Claude: Architecture questions, debugging
-- Tabnine: Context-aware suggestions
-- Average time saved: 1+ hour weekly
-
-**Key Mindset:** Continuous learning is not optional, it's survival in mobile development