@cloudkinetix/bmad-enhanced

# Learning Logger Utility ## Purpose Quietly track interaction patterns to identify friction points and success patterns, building anonymous feedback that helps improve the JIRA expansion pack for everyone. ## Privacy First Design All logging is anonymized and sanitized: - No URLs, project keys, or ticket IDs - No personal or company information - No file paths beyond `.bmad/` - Only patterns and timings ## Learning Event Types ### Struggle Indicators #### Setup Struggles ```yaml event_type: setup_struggle indicators: - multiple_mcp_attempts: count > 3 - setup_duration: time > 10_minutes - error_messages: ["authentication failed", "connection failed"] - abandoned: started_but_not_completed ``` #### Command Confusion ```yaml event_type: command_confusion indicators: - repeated_attempts: same_command_3x_in_5min - help_after_error: true - unclear_intent: ["that's not what I wanted", "how do I"] - command_variations: trying_similar_commands ``` #### Sync Difficulties ```yaml event_type: sync_difficulty indicators: - preview_then_cancel: multiple_times - field_mapping_errors: true - partial_sync_attempts: > 2 - time_to_success: > 15_minutes ``` ### Success Patterns #### Smooth Workflows ```yaml event_type: smooth_workflow indicators: - setup_time: < 5_minutes - first_try_success: true - no_help_needed: true - features_discovered: count ``` #### Feature Adoption ```yaml event_type: feature_discovery tracked: - visual_dashboard_usage - advanced_report_generation - bulk_operations - automation_setup ``` ## Logging Implementation ### Event Structure ```javascript { timestamp: "relative_time", // "morning", "afternoon", not exact session_hash: "anonymous_id", event_type: "setup_struggle", details: { phase: "mcp_configuration", attempts: 3, time_spent: "5-10min", resolution: "succeeded_with_help" } } ``` ### Aggregation Rules [[LLM: When logging events: 1. Group similar events within 5-minute windows 2. Round times to ranges (0-5min, 5-10min, 10-15min, 15+min) 3. Count patterns, not individual instances 4. Focus on workflows, not commands ]] ## Feedback File Generation ### Location `.bmad-workspace/ck-jira-integration/feedback/jira-expansion-learnings.md` ### Update Frequency - After each session ends - When reminder threshold reached - During natural breaks ### Content Structure ```markdown # JIRA Expansion Pack - Usage Learnings Generated: {{date}} Version: {{expansion_pack_version}} Sessions Analyzed: {{count}} ## Summary - Total interactions: {{interaction_count}} - Success rate: {{success_percentage}}% - Most used features: {{top_3_features}} - Average setup time: {{setup_time_range}} ## Observed Patterns ### Setup Experience - {{setup_success_rate}}% completed setup successfully - Common friction point: {{top_setup_issue}} - Average attempts needed: {{attempt_average}} ### Feature Discovery - Visual dashboard discovered by {{percentage}}% naturally - Most discovered through: {{discovery_method}} - Time to first advanced feature: {{time_range}} ### Workflow Patterns {{workflow_analysis}} ## Improvement Opportunities Based on usage patterns, consider: {{numbered_suggestions}} ## Detailed Events (Anonymized) {{event_log}} ``` ## Logging Hooks ### In Setup Task [[LLM: Track: - Time to complete each setup phase - Number of attempts per step - Error messages encountered - Whether user needed help - Final success/abandon status ]] ### In Sync Operations [[LLM: Monitor: - Sync type distribution - Preview usage patterns - Field mapping success - Batch size preferences - Error recovery attempts ]] ### In Help Commands [[LLM: Note: - Help frequency by user experience level - Topics most requested - Context when help sought - Whether help resolved issue ]] ## Smart Patterns ### Struggle Detection ```yaml patterns: learning_cliff: - help_commands > 5 in first session - abandoned_setup: true - error_rate > 50% feature_confusion: - tries: ["sync", "sync all", "sync everything"] - expects_different_behavior: true missing_mental_model: - searches_for_gui: ["where is", "how to see"] - expects_different_workflow: true ``` ### Success Detection ```yaml patterns: quick_learner: - setup_time < 3_minutes - discovers_features_naturally: true - help_usage: minimal power_user_emergence: - uses_advanced_features: true - creates_automation: true - helps_others: detected_in_queries ``` ## Reminder Triggers ### Conditions for Reminder ```yaml show_reminder_when: learning_events: >= 20 days_since_last: >= 30 current_activity: "idle_or_completed_task" not_during: ["active_sync", "setup", "urgent_work"] ``` ### Natural Moments - After successful sprint completion - During "help" command response - At end of successful bulk operation - When user says "thanks" or "done" ## Implementation Details ### Session Management [[LLM: On agent startup: 1. Generate session hash: `session_{{timestamp}}_{{random4}}` 2. Create feedback directory if needed: `.bmad-workspace/ck-jira-integration/feedback/` 3. Load existing learnings file or create new 4. Initialize event buffer in memory ]] ### Event Storage [[LLM: Event structure: ```yaml event: session_id: "{{session_hash}}" timestamp: "{{relative_time}}" # morning/afternoon/evening type: "{{event_type}}" data: - metric: value - pattern: observed anonymized: true ``` ]] ### File Operations [[LLM: Write events: 1. Buffer events in memory during session 2. On session end or natural break: - Append to `.bmad-workspace/ck-jira-integration/feedback/jira-expansion-learnings.md` - Use file locking to prevent corruption - Rotate file if >1MB 3. Never write during active operations ]] ### Privacy Implementation [[LLM: Anonymization rules: - Replace project keys with "PROJECT-\*" - Replace URLs with domain only - Convert timestamps to relative (morning/afternoon) - Hash user identifiers - Remove all file paths except .bmad/ - Generalize error messages ]] ## Implementation Notes [[LLM: Core principles: 1. Never interrupt active work 2. Log patterns, not specifics 3. Focus on improving user experience 4. Keep feedback actionable 5. Respect user privacy absolutely 6. Fail silently if storage issues 7. Never block user operations ]] ## Usage This utility is automatically loaded by the JIRA agent and operates silently. Events are logged based on: - Command patterns - Error frequencies - Time spent on tasks - Help-seeking behavior - Success indicators The accumulated learnings help identify: - Common friction points - Confusing features - Missing functionality - Documentation gaps - Workflow improvements All data is anonymous and aggregated to protect privacy while providing valuable insights for continuous improvement.