@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/dist/lib/recommendation-engine.js

@@ -0,0 +1,597 @@
+/**
+ * Recommendation Engine
+ *
+ * Transforms aggregated patterns into actionable recommendations.
+ * Prioritizes by impact and actionability, tracks dismissals,
+ * and measures recommendation effectiveness.
+ *
+ * Key capabilities:
+ * 1. Generate recommendations from pattern analysis
+ * 2. Prioritize by impact and actionability
+ * 3. Track recommendation lifecycle (created, acted, dismissed)
+ * 4. Surface top recommendations at session start
+ * 5. Learn from recommendation outcomes
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  getClaudeDir,
+  ensureDir,
+  readFile,
+  writeFile,
+  getDateTimeString,
+  getDateString,
+  log,
+} = require('./utils');
+
+// Paths
+const KNOWLEDGE_DIR = path.join(getClaudeDir(), 'knowledge');
+const AGGREGATED_DIR = path.join(KNOWLEDGE_DIR, 'aggregated');
+const RECOMMENDATIONS_FILE = path.join(AGGREGATED_DIR, 'recommendations.json');
+const HISTORY_FILE = path.join(AGGREGATED_DIR, 'recommendation-history.json');
+
+// Recommendation types
+const RECOMMENDATION_TYPES = {
+  SKILL_GAP: 'skill_gap', // You don't use skill X but it prevents Y
+  PATTERN_ALERT: 'pattern_alert', // Recurring issue detected
+  IMPROVEMENT: 'improvement', // You're getting better at X
+  SKILL_SUGGEST: 'skill_suggest', // Consider learning skill X
+  REVIEW_NEEDED: 'review_needed', // Pattern needs review/update
+  EFFICIENCY: 'efficiency', // Process optimization opportunity
+};
+
+// Priority levels
+const PRIORITIES = {
+  HIGH: 'high',
+  MEDIUM: 'medium',
+  LOW: 'low',
+};
+
+// Thresholds
+const THRESHOLDS = {
+  DISMISSAL_THRESHOLD: 3, // Stop showing after 3 dismissals
+  EXPIRATION_DAYS: 30, // Recommendations expire after 30 days
+  HIGH_PRIORITY_COUNT: 5, // 5+ occurrences = high priority
+  MEDIUM_PRIORITY_COUNT: 3, // 3+ occurrences = medium priority
+  IMPROVEMENT_THRESHOLD: -25, // -25% = improvement worthy of note
+  WORSENING_THRESHOLD: 25, // +25% = concerning trend
+};
+
+/**
+ * Load current recommendations
+ * @returns {object} { recommendations, lastUpdated }
+ */
+function loadRecommendations() {
+  ensureDir(AGGREGATED_DIR);
+
+  try {
+    if (fs.existsSync(RECOMMENDATIONS_FILE)) {
+      const content = fs.readFileSync(RECOMMENDATIONS_FILE, 'utf8');
+      return JSON.parse(content);
+    }
+  } catch (err) {
+    log(`[RecommendationEngine] Error loading recommendations: ${err.message}`);
+  }
+
+  return { recommendations: [], lastUpdated: null };
+}
+
+/**
+ * Save recommendations to disk
+ * @param {Array} recommendations - Array of recommendation objects
+ */
+function saveRecommendations(recommendations) {
+  ensureDir(AGGREGATED_DIR);
+
+  const data = {
+    recommendations,
+    lastUpdated: getDateTimeString(),
+    count: recommendations.length,
+  };
+
+  try {
+    fs.writeFileSync(RECOMMENDATIONS_FILE, JSON.stringify(data, null, 2), 'utf8');
+    return true;
+  } catch (err) {
+    log(`[RecommendationEngine] Error saving recommendations: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * Load recommendation history (for learning)
+ * @returns {object} { history, stats }
+ */
+function loadHistory() {
+  try {
+    if (fs.existsSync(HISTORY_FILE)) {
+      const content = fs.readFileSync(HISTORY_FILE, 'utf8');
+      return JSON.parse(content);
+    }
+  } catch {
+    // Start fresh
+  }
+
+  return {
+    history: [],
+    stats: {
+      total: 0,
+      acted: 0,
+      dismissed: 0,
+      expired: 0,
+    },
+  };
+}
+
+/**
+ * Save recommendation history
+ * @param {object} historyData - History data to save
+ */
+function saveHistory(historyData) {
+  ensureDir(AGGREGATED_DIR);
+
+  try {
+    fs.writeFileSync(HISTORY_FILE, JSON.stringify(historyData, null, 2), 'utf8');
+    return true;
+  } catch (err) {
+    log(`[RecommendationEngine] Error saving history: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * Generate a unique recommendation ID
+ * @returns {string} Unique ID
+ */
+function generateRecommendationId() {
+  const date = getDateString();
+  const random = Math.random().toString(36).substring(2, 8);
+  return `rec-${date}-${random}`;
+}
+
+/**
+ * Calculate priority based on pattern data
+ * @param {object} pattern - Pattern data
+ * @returns {string} Priority level
+ */
+function calculatePriority(pattern) {
+  const count = pattern.totalCount || pattern.sessionCount || 0;
+  const confidence = pattern.confidence || 0;
+
+  if (count >= THRESHOLDS.HIGH_PRIORITY_COUNT || confidence >= 0.8) {
+    return PRIORITIES.HIGH;
+  }
+
+  if (count >= THRESHOLDS.MEDIUM_PRIORITY_COUNT || confidence >= 0.6) {
+    return PRIORITIES.MEDIUM;
+  }
+
+  return PRIORITIES.LOW;
+}
+
+/**
+ * Generate recommendations from analysis data
+ * @param {object} analysis - Analysis data from cross-session-patterns
+ * @returns {object} { recommendations, summary }
+ */
+function generateRecommendations(analysis) {
+  const recommendations = [];
+  const { history } = loadHistory();
+
+  // Get dismissed recommendation IDs to avoid re-suggesting
+  const dismissedPatterns = new Set();
+  for (const item of history) {
+    if (item.outcome === 'dismissed' && item.dismissCount >= THRESHOLDS.DISMISSAL_THRESHOLD) {
+      dismissedPatterns.add(item.pattern);
+    }
+  }
+
+  // 1. Pattern alerts from high-confidence patterns
+  if (analysis.patterns?.highConfidence) {
+    for (const pattern of analysis.patterns.highConfidence) {
+      const patternKey = `${pattern.category}::${pattern.original}`;
+
+      if (dismissedPatterns.has(patternKey)) continue;
+
+      recommendations.push({
+        id: generateRecommendationId(),
+        type: RECOMMENDATION_TYPES.PATTERN_ALERT,
+        priority: calculatePriority(pattern),
+        category: pattern.category,
+        title: `Recurring: ${truncate(pattern.original, 40)}`,
+        message: `This issue appeared in ${pattern.sessionCount} sessions. ${pattern.corrected || 'Review and address.'}`,
+        action: null,
+        context: {
+          pattern: patternKey,
+          occurrences: pattern.totalCount,
+          sessions: pattern.sessionCount,
+          confidence: pattern.confidence,
+        },
+        created: getDateString(),
+        expires: getExpirationDate(),
+      });
+    }
+  }
+
+  // 2. Improvement notifications from trends
+  if (analysis.trends?.improving) {
+    for (const trend of analysis.trends.improving.slice(0, 3)) {
+      if (trend.percentChange <= THRESHOLDS.IMPROVEMENT_THRESHOLD) {
+        recommendations.push({
+          id: generateRecommendationId(),
+          type: RECOMMENDATION_TYPES.IMPROVEMENT,
+          priority: PRIORITIES.LOW,
+          category: trend.category,
+          title: `Improving: ${truncate(trend.original, 40)}`,
+          message: `Down ${Math.abs(trend.percentChange)}% recently. Keep it up!`,
+          action: null,
+          context: {
+            pattern: trend.pattern,
+            change: trend.percentChange,
+          },
+          created: getDateString(),
+          expires: getExpirationDate(7), // Short expiration for improvements
+        });
+      }
+    }
+  }
+
+  // 3. Worsening trend alerts
+  if (analysis.trends?.worsening) {
+    for (const trend of analysis.trends.worsening.slice(0, 3)) {
+      if (trend.percentChange >= THRESHOLDS.WORSENING_THRESHOLD) {
+        const patternKey = trend.pattern;
+
+        if (dismissedPatterns.has(patternKey)) continue;
+
+        recommendations.push({
+          id: generateRecommendationId(),
+          type: RECOMMENDATION_TYPES.PATTERN_ALERT,
+          priority: PRIORITIES.HIGH,
+          category: trend.category,
+          title: `Increasing: ${truncate(trend.original, 40)}`,
+          message: `Up ${trend.percentChange}% recently. Consider adding to quality gates.`,
+          action: null,
+          context: {
+            pattern: patternKey,
+            change: trend.percentChange,
+            wasCount: trend.firstPeriod,
+            nowCount: trend.secondPeriod,
+          },
+          created: getDateString(),
+          expires: getExpirationDate(),
+        });
+      }
+    }
+  }
+
+  // 4. Skill gap recommendations from skill-correction matrix
+  if (analysis.skillMatrix) {
+    const highPreventionSkills = Object.values(analysis.skillMatrix)
+      .filter((s) => s.preventionRate > 0.3 && s.applications >= 3)
+      .sort((a, b) => b.preventionRate - a.preventionRate);
+
+    for (const skill of highPreventionSkills.slice(0, 2)) {
+      recommendations.push({
+        id: generateRecommendationId(),
+        type: RECOMMENDATION_TYPES.SKILL_SUGGEST,
+        priority: PRIORITIES.MEDIUM,
+        category: 'approach',
+        title: `Skill: ${skill.skill}`,
+        message: `This skill reduces corrections by ${Math.round(skill.preventionRate * 100)}%. Used ${skill.applications} times.`,
+        action: `/${skill.skill.replace('skill-', '')}`,
+        context: {
+          skill: skill.skill,
+          preventionRate: skill.preventionRate,
+          effectiveness: skill.effectiveness,
+        },
+        created: getDateString(),
+        expires: getExpirationDate(),
+      });
+    }
+  }
+
+  // 5. Technology-specific recommendations
+  if (analysis.techPatterns) {
+    for (const [tech, data] of Object.entries(analysis.techPatterns)) {
+      if (data.correctionRate > 2 && data.topIssues.length > 0) {
+        const topIssue = data.topIssues[0];
+
+        recommendations.push({
+          id: generateRecommendationId(),
+          type: RECOMMENDATION_TYPES.EFFICIENCY,
+          priority: PRIORITIES.MEDIUM,
+          category: topIssue.category,
+          title: `${tech}: ${truncate(topIssue.original, 30)}`,
+          message: `Most common issue with ${tech} (${topIssue.count} times). Review patterns.`,
+          action: null,
+          context: {
+            technology: tech,
+            topIssue: topIssue.original,
+            count: topIssue.count,
+          },
+          created: getDateString(),
+          expires: getExpirationDate(),
+        });
+      }
+    }
+  }
+
+  // Sort by priority
+  const priorityOrder = { high: 0, medium: 1, low: 2 };
+  recommendations.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]);
+
+  // Remove duplicates by pattern
+  const seen = new Set();
+  const uniqueRecommendations = recommendations.filter((r) => {
+    const key = r.context?.pattern || r.title;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  // Save recommendations
+  saveRecommendations(uniqueRecommendations);
+
+  return {
+    recommendations: uniqueRecommendations,
+    summary: {
+      total: uniqueRecommendations.length,
+      high: uniqueRecommendations.filter((r) => r.priority === 'high').length,
+      medium: uniqueRecommendations.filter((r) => r.priority === 'medium').length,
+      low: uniqueRecommendations.filter((r) => r.priority === 'low').length,
+    },
+  };
+}
+
+/**
+ * Get top recommendations for session start
+ * @param {number} limit - Maximum number to return
+ * @returns {Array} Top recommendations
+ */
+function getSessionStartRecommendations(limit = 3) {
+  const { recommendations } = loadRecommendations();
+
+  if (!recommendations || recommendations.length === 0) {
+    return [];
+  }
+
+  const now = new Date();
+
+  // Filter out expired recommendations
+  const active = recommendations.filter((r) => {
+    if (!r.expires) return true;
+    const expDate = new Date(r.expires);
+    return expDate > now;
+  });
+
+  // Sort by priority and recency
+  const priorityOrder = { high: 0, medium: 1, low: 2 };
+  active.sort((a, b) => {
+    const priorityDiff = priorityOrder[a.priority] - priorityOrder[b.priority];
+    if (priorityDiff !== 0) return priorityDiff;
+
+    // Within same priority, prefer newer
+    return new Date(b.created) - new Date(a.created);
+  });
+
+  return active.slice(0, limit);
+}
+
+/**
+ * Dismiss a recommendation
+ * @param {string} id - Recommendation ID
+ * @param {string} reason - Reason for dismissal (optional)
+ * @returns {boolean} Success
+ */
+function dismissRecommendation(id, reason = '') {
+  const { recommendations } = loadRecommendations();
+  const historyData = loadHistory();
+
+  // Find the recommendation
+  const rec = recommendations.find((r) => r.id === id);
+  if (!rec) return false;
+
+  // Remove from active recommendations
+  const updated = recommendations.filter((r) => r.id !== id);
+  saveRecommendations(updated);
+
+  // Add to history
+  const historyEntry = historyData.history.find((h) => h.pattern === rec.context?.pattern);
+
+  if (historyEntry) {
+    historyEntry.dismissCount = (historyEntry.dismissCount || 0) + 1;
+    historyEntry.lastDismissed = getDateTimeString();
+    historyEntry.outcome = 'dismissed';
+  } else {
+    historyData.history.push({
+      pattern: rec.context?.pattern || rec.title,
+      recommendationId: id,
+      type: rec.type,
+      outcome: 'dismissed',
+      dismissCount: 1,
+      reason,
+      firstSeen: rec.created,
+      lastDismissed: getDateTimeString(),
+    });
+  }
+
+  historyData.stats.dismissed++;
+  saveHistory(historyData);
+
+  return true;
+}
+
+/**
+ * Record that a recommendation was acted upon
+ * @param {string} id - Recommendation ID
+ * @param {string} outcome - Outcome description
+ * @returns {boolean} Success
+ */
+function recordRecommendationOutcome(id, outcome = 'acted') {
+  const { recommendations } = loadRecommendations();
+  const historyData = loadHistory();
+
+  const rec = recommendations.find((r) => r.id === id);
+  if (!rec) return false;
+
+  // Remove from active
+  const updated = recommendations.filter((r) => r.id !== id);
+  saveRecommendations(updated);
+
+  // Add to history with positive outcome
+  historyData.history.push({
+    pattern: rec.context?.pattern || rec.title,
+    recommendationId: id,
+    type: rec.type,
+    outcome: outcome,
+    actedOn: getDateTimeString(),
+  });
+
+  historyData.stats.acted++;
+  saveHistory(historyData);
+
+  return true;
+}
+
+/**
+ * Get recommendation statistics
+ * @returns {object} Statistics about recommendations
+ */
+function getRecommendationStats() {
+  const { recommendations } = loadRecommendations();
+  const historyData = loadHistory();
+
+  const active = recommendations.filter((r) => {
+    if (!r.expires) return true;
+    return new Date(r.expires) > new Date();
+  });
+
+  return {
+    active: active.length,
+    byPriority: {
+      high: active.filter((r) => r.priority === 'high').length,
+      medium: active.filter((r) => r.priority === 'medium').length,
+      low: active.filter((r) => r.priority === 'low').length,
+    },
+    byType: {
+      pattern_alert: active.filter((r) => r.type === RECOMMENDATION_TYPES.PATTERN_ALERT).length,
+      improvement: active.filter((r) => r.type === RECOMMENDATION_TYPES.IMPROVEMENT).length,
+      skill_suggest: active.filter((r) => r.type === RECOMMENDATION_TYPES.SKILL_SUGGEST).length,
+      efficiency: active.filter((r) => r.type === RECOMMENDATION_TYPES.EFFICIENCY).length,
+    },
+    history: historyData.stats,
+  };
+}
+
+/**
+ * Format recommendations for display
+ * @param {Array} recommendations - Recommendations to format
+ * @returns {string} Formatted string
+ */
+function formatRecommendations(recommendations) {
+  if (!recommendations || recommendations.length === 0) {
+    return 'No recommendations at this time.';
+  }
+
+  let output = '';
+
+  for (const rec of recommendations) {
+    const emoji = rec.priority === 'high' ? '🔴' : rec.priority === 'medium' ? '🟠' : '🟡';
+
+    output += `${emoji} ${rec.title}\n`;
+    output += `   ${rec.message}\n`;
+
+    if (rec.action) {
+      output += `   Action: ${rec.action}\n`;
+    }
+
+    output += '\n';
+  }
+
+  return output;
+}
+
+/**
+ * Clear expired recommendations
+ * @returns {number} Number of recommendations cleared
+ */
+function clearExpiredRecommendations() {
+  const { recommendations } = loadRecommendations();
+  const historyData = loadHistory();
+  const now = new Date();
+
+  const active = [];
+  let expired = 0;
+
+  for (const rec of recommendations) {
+    if (rec.expires && new Date(rec.expires) <= now) {
+      expired++;
+
+      // Add to history as expired
+      historyData.history.push({
+        pattern: rec.context?.pattern || rec.title,
+        recommendationId: rec.id,
+        type: rec.type,
+        outcome: 'expired',
+        expiredOn: getDateTimeString(),
+      });
+    } else {
+      active.push(rec);
+    }
+  }
+
+  if (expired > 0) {
+    saveRecommendations(active);
+    historyData.stats.expired += expired;
+    saveHistory(historyData);
+  }
+
+  return expired;
+}
+
+// Helper functions
+
+/**
+ * Truncate string to specified length
+ */
+function truncate(str, length) {
+  if (!str) return '';
+  if (str.length <= length) return str;
+  return str.substring(0, length - 3) + '...';
+}
+
+/**
+ * Get expiration date
+ * @param {number} days - Days from now (default: 30)
+ */
+function getExpirationDate(days = THRESHOLDS.EXPIRATION_DAYS) {
+  const date = new Date();
+  date.setDate(date.getDate() + days);
+  return date.toISOString().split('T')[0];
+}
+
+module.exports = {
+  // Core functions
+  generateRecommendations,
+  getSessionStartRecommendations,
+
+  // Lifecycle management
+  dismissRecommendation,
+  recordRecommendationOutcome,
+  clearExpiredRecommendations,
+
+  // Data access
+  loadRecommendations,
+  saveRecommendations,
+  getRecommendationStats,
+
+  // Formatting
+  formatRecommendations,
+
+  // Constants
+  RECOMMENDATION_TYPES,
+  PRIORITIES,
+  THRESHOLDS,
+};