Merge pull request #4222 from anyproto/ios-5420-restructure-and-update-ai-flow

IOS-5420 Add analytics-developer skill and update CLAUDE.md with skill usage guidance

Author: ignatovv

.claude/hooks/skill-rules.json

@@ -205,21 +205,27 @@
       "description": "Smart router to skills/hooks management (→ SKILLS_MANAGEMENT_GUIDE.md). Troubleshoot activation, add keywords, fine-tune system",
       "promptTriggers": {
         "keywords": [
+          "activation log",
+          "add keyword",
+          "check logs",
+          "claude.md",
+          "false negative",
+          "false positive",
+          "fine-tune",
+          "hook",
+          "hooks system",
+          "instances",
+          "knowledge",
+          "proactive",
           "skill activation",
           "skill didn't activate",
-          "hook",
-          "troubleshoot skill",
-          "fine-tune",
-          "add keyword",
+          "skill not working",
           "skill-rules.json",
-          "activation log",
-          "why didn't",
-          "false positive",
-          "false negative",
-          "check logs",
           "skills system",
-          "hooks system",
-          "skill not working"
+          "solidify",
+          "suggested",
+          "troubleshoot skill",
+          "why didn't"
         ],
         "intentPatterns": [
           "(check|view|show).*?(activation|log|skill)",
@@ -327,6 +333,60 @@
           "@State.*FeatureFlags"
         ]
       }
+    },
+    "analytics-developer": {
+      "type": "domain",
+      "priority": "high",
+      "description": "Smart router to analytics system (→ ANALYTICS_PATTERNS.md). Event logging, route tracking, AnalyticsConstants enums",
+      "promptTriggers": {
+        "keywords": [
+          "analytics",
+          "route tracking",
+          "logEvent",
+          "AnytypeAnalytics",
+          "AnalyticsConstants",
+          "analytics event",
+          "track route",
+          "event properties",
+          "AnalyticsEventsPropertiesKey",
+          "route enum",
+          "HomeWidgetRoute",
+          "analytics pattern",
+          "log screen",
+          "log click",
+          "logScreen",
+          "logClick",
+          "amplitude",
+          "analytics tracking",
+          "user analytics"
+        ],
+        "intentPatterns": [
+          "(add|create|implement).*?(analytics|event|route tracking)",
+          "(track|log).*?(route|screen|click|user|event|action)",
+          "(update|modify).*?(analytics|event|route)",
+          "(how to|where).*?(analytics|track|log|event)",
+          "(define|add).*?(route enum|analytics enum)"
+        ]
+      },
+      "fileTriggers": {
+        "pathPatterns": [
+          "**/AnalyticsConstants.swift",
+          "**/AnytypeAnalytics+Events.swift",
+          "**/Analytics/**/*.swift",
+          "**/ANALYTICS_PATTERNS.md"
+        ],
+        "contentPatterns": [
+          "AnytypeAnalytics\\.instance\\(\\)",
+          "logEvent\\(",
+          "AnalyticsEventsPropertiesKey\\.",
+          "enum.*Route.*String",
+          "\\.analyticsValue",
+          "\\.analyticsType",
+          "\\.analyticsId",
+          "logScreen",
+          "logClick"
+        ]
+      }
     }
   },
   "config": {

.claude/hooks/skill-rules.json.tmp

@@ -0,0 +1,285 @@
+# Analytics Developer (Smart Router)
+
+## Purpose
+Context-aware routing to the Anytype iOS analytics system. Helps you add analytics events, track user routes, and maintain consistent analytics patterns.
+
+## When Auto-Activated
+- Working with analytics events or AnytypeAnalytics
+- Adding route tracking or event properties
+- Modifying `AnalyticsConstants.swift` or `AnytypeAnalytics+Events.swift`
+- Keywords: analytics, route tracking, logEvent, AnytypeAnalytics, AnalyticsConstants
+
+## 🚨 CRITICAL RULES (NEVER VIOLATE)
+
+1. **ALWAYS define route enums in AnalyticsConstants.swift** - Never hardcode route strings
+2. **ALWAYS use existing property keys** - Use `AnalyticsEventsPropertiesKey.*`
+3. **NEVER use string literals for routes** - Use typed enums with `.rawValue`
+4. **ALWAYS use `.compactMapValues { $0 }` for optional properties** - Removes nil values
+5. **ALWAYS track route context** - Know how users reached a feature
+
+## 📋 Quick Workflow
+
+### Adding New Analytics Event
+
+1. **Define route enum** (if needed): Add to `AnalyticsConstants.swift`
+2. **Add event method**: Add to `AnytypeAnalytics+Events.swift`
+3. **Use in code**: Call `AnytypeAnalytics.instance().logYourEvent(...)`
+
+### Adding Route Tracking to Existing Screen
+
+1. **Define route enum**: Add `YourFeatureRoute` to `AnalyticsConstants.swift`
+2. **Update data model**: Add `route: YourFeatureRoute?` parameter
+3. **Pass through hierarchy**: Coordinator → View → ViewModel
+4. **Update analytics call**: Pass route to existing log method
+
+## 🎯 Common Patterns
+
+### Pattern 1: Screen Analytics (onAppear)
+
+```swift
+// ViewModel
+final class HomeWidgetsViewModel {
+    let route: HomeWidgetRoute?
+
+    func onAppear() {
+        AnytypeAnalytics.instance().logScreenWidget(route: route)
+    }
+}
+
+// Analytics method (AnytypeAnalytics+Events.swift)
+func logScreenWidget(route: HomeWidgetRoute?) {
+    logEvent("ScreenWidget", withEventProperties: [
+        AnalyticsEventsPropertiesKey.route: route?.rawValue
+    ].compactMapValues { $0 })
+}
+
+// Route enum (AnalyticsConstants.swift)
+enum HomeWidgetRoute: String, Hashable, Codable {
+    case home = "Home"
+    case space = "Space"
+    case appLaunch = "AppLaunch"
+}
+```
+
+### Pattern 2: Button Click Analytics
+
+```swift
+// ViewModel
+func onTapShare() {
+    AnytypeAnalytics.instance().logClickShare(type: .link, route: .settings)
+    output?.onShareSelected()
+}
+
+// Analytics method
+func logClickShare(type: ShareType, route: ShareRoute) {
+    logEvent("ClickShare", withEventProperties: [
+        AnalyticsEventsPropertiesKey.type: type.rawValue,
+        AnalyticsEventsPropertiesKey.route: route.rawValue
+    ])
+}
+```
+
+### Pattern 3: Multi-Space Events
+
+```swift
+func logCreateObject(objectType: AnalyticsObjectType, spaceId: String, route: AnalyticsEventsRouteKind) {
+    logEvent("CreateObject", spaceId: spaceId, withEventProperties: [
+        AnalyticsEventsPropertiesKey.objectType: objectType.analyticsId,
+        AnalyticsEventsPropertiesKey.route: route.rawValue
+    ])
+}
+```
+
+## 🗂️ Analytics File Structure
+
+### Key Files
+- **AnalyticsConstants.swift** - All route enums, property keys (400+ lines)
+- **AnytypeAnalytics+Events.swift** - All event methods (1,500+ lines)
+- **Converters/** - Domain type → analytics value converters
+
+### Route Enum Location
+
+**Always add to AnalyticsConstants.swift**, grouped by feature:
+
+```swift
+// Widget-related routes
+enum AnalyticsWidgetRoute: String {
+    case addWidget = "AddWidget"
+    case inner = "Inner"
+}
+
+enum HomeWidgetRoute: String, Hashable, Codable {
+    case home = "Home"
+    case space = "Space"
+    case appLaunch = "AppLaunch"
+}
+
+// Screen navigation routes
+enum SettingsSpaceShareRoute: String {
+    case settings = "Settings"
+    case navigation = "Navigation"
+    case chat = "Chat"
+}
+```
+
+## 📈 Route Tracking Implementation
+
+### Step-by-Step: Adding Route to Screen
+
+**Example: Adding route tracking to ScreenWidget**
+
+1. **Define route enum** (AnalyticsConstants.swift):
+```swift
+enum HomeWidgetRoute: String, Hashable, Codable {
+    case home = "Home"            // Home button click
+    case space = "Space"          // Space selection
+    case appLaunch = "AppLaunch"  // App launch
+}
+```
+
+2. **Update data model**:
+```swift
+struct HomeWidgetData: Hashable {
+    let spaceId: String
+    let route: HomeWidgetRoute?  // Add route parameter
+}
+```
+
+3. **Pass through view hierarchy**:
+```swift
+// Coordinator
+HomeWidgetsView(info: info, output: model, route: data.route)
+
+// View
+HomeWidgetsViewModel(info: info, output: output, route: route)
+```
+
+4. **Update analytics call**:
+```swift
+// ViewModel
+func onAppear() {
+    AnytypeAnalytics.instance().logScreenWidget(route: route)
+}
+
+// Analytics method
+func logScreenWidget(route: HomeWidgetRoute?) {
+    logEvent("ScreenWidget", withEventProperties: [
+        AnalyticsEventsPropertiesKey.route: route?.rawValue
+    ].compactMapValues { $0 })
+}
+```
+
+5. **Set route at navigation points**:
+```swift
+// Home button
+let data = HomeWidgetData(spaceId: spaceId, route: .home)
+
+// Space selection
+let data = HomeWidgetData(spaceId: spaceId, route: .space)
+
+// App launch
+let data = HomeWidgetData(spaceId: spaceId, route: .appLaunch)
+```
+
+## 🔧 Common Property Keys
+
+Located in `AnalyticsEventsPropertiesKey`:
+
+| Key | Usage | Example |
+|-----|-------|---------|
+| `route` | Navigation context | `.home`, `.navigation`, `.widget` |
+| `type` | Primary classification | `.image`, `.video`, `.file` |
+| `objectType` | Object type ID | `type.analyticsType.analyticsId` |
+| `spaceId` | Space identifier | `document.spaceId` |
+| `count` | Quantity values | Number of items |
+| `format` | Data format | File format, date format |
+
+## ⚠️ Common Mistakes
+
+### ❌ Hardcoded Route Strings
+```swift
+// WRONG
+AnytypeAnalytics.instance().logScreenWidget(route: "Home")
+
+// CORRECT
+AnytypeAnalytics.instance().logScreenWidget(route: .home)
+```
+
+### ❌ Route Enum in Wrong File
+```swift
+// WRONG - defined in feature file
+enum HomeWidgetRoute: String {
+    case home = "Home"
+}
+
+// CORRECT - defined in AnalyticsConstants.swift
+```
+
+### ❌ Missing compactMapValues
+```swift
+// WRONG - will include nil values as NSNull
+[AnalyticsEventsPropertiesKey.route: route?.rawValue]
+
+// CORRECT - removes nil values
+[AnalyticsEventsPropertiesKey.route: route?.rawValue].compactMapValues { $0 }
+```
+
+### ❌ Using String Literals for Property Keys
+```swift
+// WRONG
+["route": route.rawValue]
+
+// CORRECT
+[AnalyticsEventsPropertiesKey.route: route.rawValue]
+```
+
+## 🔍 Finding Existing Patterns
+
+```bash
+# Search for existing events
+rg "logEvent.*EventName" Anytype/Sources/Analytics/
+
+# Find route enums
+rg "enum.*Route.*String" Anytype/Sources/Analytics/AnalyticsConstants.swift
+
+# Find property usage
+rg "AnalyticsEventsPropertiesKey\." Anytype/Sources/Analytics/
+
+# Find screen analytics
+rg "func logScreen" Anytype/Sources/Analytics/AnytypeAnalytics+Events.swift
+```
+
+## 📚 Complete Documentation
+
+**Full Guide**: `Anytype/Sources/PresentationLayer/Common/Analytics/ANALYTICS_PATTERNS.md`
+
+For comprehensive coverage of:
+- Analytics system architecture
+- All analytics patterns (user actions, screen navigation, content creation)
+- Route context tracking best practices
+- Platform-specific considerations
+- Testing analytics events
+- Migration patterns for adding parameters
+- Complete examples and code snippets
+
+## ✅ Workflow Checklist
+
+When adding analytics:
+
+- [ ] Route enum added to `AnalyticsConstants.swift`
+- [ ] Event method added to `AnytypeAnalytics+Events.swift`
+- [ ] Used existing property keys (`AnalyticsEventsPropertiesKey.*`)
+- [ ] Optional properties use `.compactMapValues { $0 }`
+- [ ] Route passed through view hierarchy (if tracking navigation)
+- [ ] No hardcoded strings for routes or property keys
+- [ ] Followed existing naming conventions (PascalCase events, camelCase properties)
+
+## 🔗 Related Skills & Docs
+
+- **ios-dev-guidelines** → `IOS_DEVELOPMENT_GUIDE.md` - MVVM/Coordinator patterns for passing analytics data
+- **code-generation-developer** → Understanding the build system
+- **design-system-developer** → Tracking UI interactions
+
+---
+
+**Navigation**: This is a smart router. For deep patterns and examples, always refer to `ANALYTICS_PATTERNS.md`.