@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/scripts/quarterly-report.js

@@ -0,0 +1,692 @@
+#!/usr/bin/env node
+/**
+ * Quarterly Report Generator
+ *
+ * Generates comprehensive quarterly review report analyzing skill effectiveness,
+ * identifying deprecation/promotion candidates, and tracking knowledge asset value.
+ *
+ * Usage:
+ *   npm run quarterly:report              # Generate current quarter report
+ *   npm run quarterly:report --json       # Output as JSON
+ *   npm run quarterly:report --verbose    # Include per-skill details
+ *   npm run quarterly:report --status     # Show current quarter status only
+ *
+ * Output: ~/.claude/knowledge/reports/quarterly-Q[X]-[YEAR].md
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Paths
+const CLAUDE_DIR = path.join(os.homedir(), '.claude');
+const KNOWLEDGE_DIR = path.join(CLAUDE_DIR, 'knowledge');
+const REPORTS_DIR = path.join(KNOWLEDGE_DIR, 'reports');
+const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT || path.join(__dirname, '..');
+const VERSIONS_FILE = path.join(PLUGIN_ROOT, 'config', 'versions.json');
+
+// Try to load optional dependencies
+let skillEffectiveness, assetValue, crossSessionPatterns;
+
+try {
+  skillEffectiveness = require('./lib/skill-effectiveness');
+} catch (e) {
+  skillEffectiveness = null;
+}
+
+try {
+  assetValue = require('./lib/asset-value');
+} catch (e) {
+  assetValue = null;
+}
+
+try {
+  crossSessionPatterns = require('./lib/cross-session-patterns');
+} catch (e) {
+  crossSessionPatterns = null;
+}
+
+/**
+ * Ensure directories exist.
+ */
+function ensureDirectories() {
+  if (!fs.existsSync(CLAUDE_DIR)) {
+    fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+  }
+  if (!fs.existsSync(KNOWLEDGE_DIR)) {
+    fs.mkdirSync(KNOWLEDGE_DIR, { recursive: true });
+  }
+  if (!fs.existsSync(REPORTS_DIR)) {
+    fs.mkdirSync(REPORTS_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Parse command line arguments.
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  return {
+    json: args.includes('--json'),
+    verbose: args.includes('--verbose') || args.includes('-v'),
+    status: args.includes('--status'),
+    help: args.includes('--help') || args.includes('-h'),
+    quarter: args.find((a) => a.startsWith('--quarter='))?.split('=')[1],
+    year: args.find((a) => a.startsWith('--year='))?.split('=')[1],
+  };
+}
+
+/**
+ * Get current quarter info.
+ */
+function getCurrentQuarter() {
+  const now = new Date();
+  const quarter = Math.ceil((now.getMonth() + 1) / 3);
+  const year = now.getFullYear();
+  return { quarter, year };
+}
+
+/**
+ * Get quarter date range.
+ */
+function getQuarterDateRange(quarter, year) {
+  const startMonth = (quarter - 1) * 3;
+  const start = new Date(year, startMonth, 1);
+  const end = new Date(year, startMonth + 3, 0);
+  return { start, end };
+}
+
+/**
+ * Load version registry.
+ */
+function loadVersionRegistry() {
+  try {
+    if (fs.existsSync(VERSIONS_FILE)) {
+      return JSON.parse(fs.readFileSync(VERSIONS_FILE, 'utf8'));
+    }
+  } catch (err) {
+    console.error(`[Quarterly] Warning: Could not load versions.json: ${err.message}`);
+  }
+  return { skills: {}, agents: {} };
+}
+
+/**
+ * Load skill effectiveness data.
+ */
+function loadEffectivenessData() {
+  const effectivenessFile = path.join(KNOWLEDGE_DIR, 'skill-effectiveness.json');
+  try {
+    if (fs.existsSync(effectivenessFile)) {
+      return JSON.parse(fs.readFileSync(effectivenessFile, 'utf8'));
+    }
+  } catch (err) {
+    console.error(`[Quarterly] Warning: Could not load effectiveness data: ${err.message}`);
+  }
+  return { skills: {}, summary: {} };
+}
+
+/**
+ * Analyze skill trends.
+ */
+function analyzeSkillTrends(effectivenessData, versions) {
+  const trends = {
+    improving: [],
+    declining: [],
+    stable: [],
+    new: [],
+    inactive: [],
+  };
+
+  const allSkills = { ...versions.skills };
+
+  for (const [skillName, skillInfo] of Object.entries(allSkills)) {
+    const effectiveness = effectivenessData.skills?.[skillName];
+
+    if (!effectiveness || effectiveness.applicationCount === 0) {
+      // Check if truly new or just unused
+      if (skillInfo.introduced === versions.version) {
+        trends.new.push({ name: skillName, ...skillInfo });
+      } else {
+        trends.inactive.push({ name: skillName, ...skillInfo, daysSinceLastUse: 90 });
+      }
+      continue;
+    }
+
+    const rate = effectiveness.effectivenessRate || 0;
+    const prevRate = effectiveness.previousQuarterRate || rate;
+    const change = rate - prevRate;
+
+    const skillData = {
+      name: skillName,
+      effectiveness: rate,
+      previousEffectiveness: prevRate,
+      change,
+      usageCount: effectiveness.applicationCount || 0,
+      ...skillInfo,
+    };
+
+    if (change > 0.1) {
+      trends.improving.push(skillData);
+    } else if (change < -0.1) {
+      trends.declining.push(skillData);
+    } else {
+      trends.stable.push(skillData);
+    }
+  }
+
+  // Sort by effectiveness
+  trends.improving.sort((a, b) => b.change - a.change);
+  trends.declining.sort((a, b) => a.change - b.change);
+  trends.stable.sort((a, b) => b.effectiveness - a.effectiveness);
+
+  return trends;
+}
+
+/**
+ * Identify deprecation candidates.
+ */
+function identifyDeprecationCandidates(effectivenessData, versions) {
+  const candidates = [];
+  const EFFECTIVENESS_THRESHOLD = 0.4;
+  const MIN_USES = 10;
+  const INACTIVE_DAYS = 90;
+
+  for (const [skillName, skillInfo] of Object.entries(versions.skills)) {
+    if (skillInfo.status === 'deprecated') continue;
+
+    const effectiveness = effectivenessData.skills?.[skillName];
+
+    // Check low effectiveness
+    if (effectiveness && effectiveness.applicationCount >= MIN_USES) {
+      const rate = effectiveness.effectivenessRate || 0;
+      if (rate < EFFECTIVENESS_THRESHOLD) {
+        candidates.push({
+          name: skillName,
+          reason: 'low_effectiveness',
+          effectiveness: rate,
+          usageCount: effectiveness.applicationCount,
+          justification: `Effectiveness ${(rate * 100).toFixed(0)}% after ${effectiveness.applicationCount} uses`,
+          severity: rate < 0.2 ? 'high' : 'medium',
+        });
+        continue;
+      }
+    }
+
+    // Check inactivity
+    if (!effectiveness || effectiveness.applicationCount === 0) {
+      const lastUsed = effectiveness?.lastUsed;
+      if (lastUsed) {
+        const daysSince = Math.floor(
+          (Date.now() - new Date(lastUsed).getTime()) / (1000 * 60 * 60 * 24)
+        );
+        if (daysSince > INACTIVE_DAYS) {
+          candidates.push({
+            name: skillName,
+            reason: 'inactive',
+            daysSinceLastUse: daysSince,
+            justification: `Not used in ${daysSince} days`,
+            severity: 'low',
+          });
+        }
+      }
+    }
+  }
+
+  // Sort by severity
+  const severityOrder = { high: 0, medium: 1, low: 2 };
+  candidates.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+
+  return candidates;
+}
+
+/**
+ * Identify promotion candidates.
+ */
+function identifyPromotionCandidates(effectivenessData) {
+  const candidates = [];
+  const EFFECTIVENESS_THRESHOLD = 0.9;
+  const MIN_USES = 20;
+
+  // Check learned skills
+  const learnedSkillsDir = path.join(CLAUDE_DIR, 'skills', 'learned');
+  if (fs.existsSync(learnedSkillsDir)) {
+    try {
+      const learnedSkills = fs.readdirSync(learnedSkillsDir).filter((f) => f.endsWith('.md'));
+
+      for (const skillFile of learnedSkills) {
+        const skillName = path.basename(skillFile, '.md');
+        const effectiveness = effectivenessData.skills?.[skillName];
+
+        if (effectiveness && effectiveness.applicationCount >= MIN_USES) {
+          const rate = effectiveness.effectivenessRate || 0;
+          if (rate >= EFFECTIVENESS_THRESHOLD) {
+            candidates.push({
+              name: skillName,
+              type: 'learned',
+              effectiveness: rate,
+              usageCount: effectiveness.applicationCount,
+              justification: `${(rate * 100).toFixed(0)}% effectiveness over ${effectiveness.applicationCount} uses`,
+            });
+          }
+        }
+      }
+    } catch (err) {
+      // Learned skills directory doesn't exist or is empty
+    }
+  }
+
+  candidates.sort((a, b) => b.effectiveness - a.effectiveness);
+  return candidates;
+}
+
+/**
+ * Get asset value summary.
+ */
+function getAssetValueSummary() {
+  if (assetValue && typeof assetValue.getAllAssetValues === 'function') {
+    try {
+      return assetValue.getAllAssetValues();
+    } catch (err) {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Generate executive summary.
+ */
+function generateExecutiveSummary(data) {
+  const { trends, deprecationCandidates, promotionCandidates, assetSummary } = data;
+
+  const totalSkills =
+    trends.improving.length +
+    trends.declining.length +
+    trends.stable.length +
+    trends.new.length +
+    trends.inactive.length;
+
+  const avgEffectiveness =
+    [...trends.improving, ...trends.declining, ...trends.stable]
+      .filter((s) => s.effectiveness)
+      .reduce((sum, s) => sum + s.effectiveness, 0) /
+      Math.max([...trends.improving, ...trends.declining, ...trends.stable].length, 1) || 0;
+
+  return {
+    totalSkills,
+    avgEffectiveness,
+    improving: trends.improving.length,
+    declining: trends.declining.length,
+    stable: trends.stable.length,
+    inactive: trends.inactive.length,
+    deprecationCandidates: deprecationCandidates.length,
+    promotionCandidates: promotionCandidates.length,
+    totalAssetValue: assetSummary?.summary?.totalEstimatedValue || 0,
+    criticalActions: deprecationCandidates.filter((c) => c.severity === 'high').length,
+  };
+}
+
+/**
+ * Generate markdown report.
+ */
+function generateMarkdownReport(data, options) {
+  const {
+    quarter,
+    year,
+    summary,
+    trends,
+    deprecationCandidates,
+    promotionCandidates,
+    assetSummary,
+  } = data;
+
+  const lines = [];
+
+  // Header
+  lines.push(`# Quarterly Review Report: Q${quarter} ${year}`);
+  lines.push('');
+  lines.push(`Generated: ${new Date().toISOString()}`);
+  lines.push('');
+
+  // Executive Summary
+  lines.push('## Executive Summary');
+  lines.push('');
+  lines.push('| Metric | Value |');
+  lines.push('|--------|-------|');
+  lines.push(`| Total Skills/Agents | ${summary.totalSkills} |`);
+  lines.push(`| Average Effectiveness | ${(summary.avgEffectiveness * 100).toFixed(0)}% |`);
+  lines.push(`| Improving | ${summary.improving} |`);
+  lines.push(`| Declining | ${summary.declining} |`);
+  lines.push(`| Stable | ${summary.stable} |`);
+  lines.push(`| Inactive (90+ days) | ${summary.inactive} |`);
+  lines.push(`| Deprecation Candidates | ${summary.deprecationCandidates} |`);
+  lines.push(`| Promotion Candidates | ${summary.promotionCandidates} |`);
+  if (summary.totalAssetValue > 0) {
+    lines.push(`| Total Asset Value | $${summary.totalAssetValue.toLocaleString()} |`);
+  }
+  lines.push('');
+
+  if (summary.criticalActions > 0) {
+    lines.push(
+      `> **Action Required:** ${summary.criticalActions} skill(s) require immediate attention.`
+    );
+    lines.push('');
+  }
+
+  // Skill Effectiveness Analysis
+  lines.push('## Skill Effectiveness Analysis');
+  lines.push('');
+
+  if (trends.improving.length > 0) {
+    lines.push('### Improving Skills');
+    lines.push('');
+    lines.push('| Skill | Effectiveness | Change | Uses |');
+    lines.push('|-------|--------------|--------|------|');
+    for (const skill of trends.improving.slice(0, 10)) {
+      const change =
+        skill.change > 0
+          ? `+${(skill.change * 100).toFixed(0)}%`
+          : `${(skill.change * 100).toFixed(0)}%`;
+      lines.push(
+        `| ${skill.name} | ${(skill.effectiveness * 100).toFixed(0)}% | ${change} | ${skill.usageCount} |`
+      );
+    }
+    lines.push('');
+  }
+
+  if (trends.declining.length > 0) {
+    lines.push('### Declining Skills');
+    lines.push('');
+    lines.push('| Skill | Effectiveness | Change | Uses |');
+    lines.push('|-------|--------------|--------|------|');
+    for (const skill of trends.declining.slice(0, 10)) {
+      const change = `${(skill.change * 100).toFixed(0)}%`;
+      lines.push(
+        `| ${skill.name} | ${(skill.effectiveness * 100).toFixed(0)}% | ${change} | ${skill.usageCount} |`
+      );
+    }
+    lines.push('');
+  }
+
+  if (options.verbose && trends.stable.length > 0) {
+    lines.push('### Stable Skills');
+    lines.push('');
+    lines.push('| Skill | Effectiveness | Uses |');
+    lines.push('|-------|--------------|------|');
+    for (const skill of trends.stable) {
+      lines.push(
+        `| ${skill.name} | ${(skill.effectiveness * 100).toFixed(0)}% | ${skill.usageCount} |`
+      );
+    }
+    lines.push('');
+  }
+
+  // Deprecation Recommendations
+  lines.push('## Deprecation Recommendations');
+  lines.push('');
+
+  if (deprecationCandidates.length === 0) {
+    lines.push('No deprecation candidates identified this quarter.');
+    lines.push('');
+  } else {
+    lines.push('| Skill | Reason | Severity | Justification |');
+    lines.push('|-------|--------|----------|---------------|');
+    for (const candidate of deprecationCandidates) {
+      const severityEmoji =
+        candidate.severity === 'high' ? '🔴' : candidate.severity === 'medium' ? '🟠' : '🟡';
+      lines.push(
+        `| ${candidate.name} | ${candidate.reason} | ${severityEmoji} ${candidate.severity} | ${candidate.justification} |`
+      );
+    }
+    lines.push('');
+
+    lines.push('### Deprecation Commands');
+    lines.push('');
+    lines.push('```bash');
+    for (const candidate of deprecationCandidates.filter((c) => c.severity === 'high')) {
+      lines.push(`npm run skill:deprecate ${candidate.name} --removal-target 2.0.0`);
+    }
+    lines.push('```');
+    lines.push('');
+  }
+
+  // Promotion Recommendations
+  lines.push('## Promotion Recommendations');
+  lines.push('');
+
+  if (promotionCandidates.length === 0) {
+    lines.push('No promotion candidates identified this quarter.');
+    lines.push('');
+  } else {
+    lines.push('| Skill | Type | Effectiveness | Uses |');
+    lines.push('|-------|------|--------------|------|');
+    for (const candidate of promotionCandidates) {
+      lines.push(
+        `| ${candidate.name} | ${candidate.type} | ${(candidate.effectiveness * 100).toFixed(0)}% | ${candidate.usageCount} |`
+      );
+    }
+    lines.push('');
+  }
+
+  // Asset Value Report
+  if (assetSummary && assetSummary.summary) {
+    lines.push('## Knowledge Asset Value');
+    lines.push('');
+    lines.push('| Category | Count | Value |');
+    lines.push('|----------|-------|-------|');
+    if (assetSummary.summary.byCategory) {
+      for (const [category, stats] of Object.entries(assetSummary.summary.byCategory)) {
+        if (stats.count > 0) {
+          lines.push(`| ${category} | ${stats.count} | $${stats.totalValue.toLocaleString()} |`);
+        }
+      }
+    }
+    lines.push(
+      `| **Total** | **${assetSummary.summary.totalAssets}** | **$${assetSummary.summary.totalEstimatedValue.toLocaleString()}** |`
+    );
+    lines.push('');
+  }
+
+  // Next Steps
+  lines.push('## Next Steps');
+  lines.push('');
+  lines.push('1. Review deprecation candidates in team meeting');
+  lines.push('2. Create migration guides for approved deprecations');
+  lines.push('3. Execute deprecations using `npm run skill:deprecate`');
+  lines.push('4. Update CHANGELOG.md with changes');
+  lines.push('5. Notify team of upcoming deprecations');
+  lines.push('');
+
+  // Footer
+  lines.push('---');
+  lines.push('');
+  lines.push('*Generated by CloudStream Claude Code Quarterly Report*');
+  lines.push('');
+  lines.push('See `docs/quarterly-review-process.md` for full review process documentation.');
+
+  return lines.join('\n');
+}
+
+/**
+ * Output terminal report.
+ */
+function outputTerminal(data) {
+  const { quarter, year, summary, trends, deprecationCandidates, promotionCandidates } = data;
+
+  console.log('');
+  console.log('='.repeat(60));
+  console.log(`  QUARTERLY REVIEW REPORT: Q${quarter} ${year}`);
+  console.log('='.repeat(60));
+  console.log('');
+
+  // Summary
+  console.log('EXECUTIVE SUMMARY');
+  console.log('-'.repeat(40));
+  console.log(`  Total Skills/Agents:     ${summary.totalSkills}`);
+  console.log(`  Average Effectiveness:   ${(summary.avgEffectiveness * 100).toFixed(0)}%`);
+  console.log(`  Improving:               ${summary.improving}`);
+  console.log(`  Declining:               ${summary.declining}`);
+  console.log(`  Stable:                  ${summary.stable}`);
+  console.log(`  Inactive (90+ days):     ${summary.inactive}`);
+  console.log('');
+
+  // Deprecation candidates
+  if (deprecationCandidates.length > 0) {
+    console.log('DEPRECATION CANDIDATES');
+    console.log('-'.repeat(40));
+    for (const candidate of deprecationCandidates) {
+      const emoji =
+        candidate.severity === 'high' ? '[!]' : candidate.severity === 'medium' ? '[*]' : '[-]';
+      console.log(`  ${emoji} ${candidate.name}`);
+      console.log(`      ${candidate.justification}`);
+    }
+    console.log('');
+  }
+
+  // Promotion candidates
+  if (promotionCandidates.length > 0) {
+    console.log('PROMOTION CANDIDATES');
+    console.log('-'.repeat(40));
+    for (const candidate of promotionCandidates) {
+      console.log(`  [+] ${candidate.name}`);
+      console.log(`      ${candidate.justification}`);
+    }
+    console.log('');
+  }
+
+  // Asset value
+  if (summary.totalAssetValue > 0) {
+    console.log('KNOWLEDGE ASSET VALUE');
+    console.log('-'.repeat(40));
+    console.log(`  Total Value: $${summary.totalAssetValue.toLocaleString()}`);
+    console.log('');
+  }
+
+  // Actions
+  if (summary.criticalActions > 0) {
+    console.log('ACTION REQUIRED');
+    console.log('-'.repeat(40));
+    console.log(`  ${summary.criticalActions} skill(s) need immediate attention.`);
+    console.log('  Run with --verbose for details.');
+    console.log('');
+  }
+
+  console.log('Report saved to: ~/.claude/knowledge/reports/');
+  console.log('');
+}
+
+/**
+ * Show status only.
+ */
+function showStatus(data) {
+  const { quarter, year, summary } = data;
+
+  console.log('');
+  console.log(`Quarterly Review Status: Q${quarter} ${year}`);
+  console.log('-'.repeat(40));
+  console.log(`  Skills Analyzed:         ${summary.totalSkills}`);
+  console.log(`  Avg Effectiveness:       ${(summary.avgEffectiveness * 100).toFixed(0)}%`);
+  console.log(`  Deprecation Candidates:  ${summary.deprecationCandidates}`);
+  console.log(`  Promotion Candidates:    ${summary.promotionCandidates}`);
+  console.log(`  Critical Actions:        ${summary.criticalActions}`);
+  console.log('');
+  console.log('Run `npm run quarterly:report` for full report.');
+  console.log('');
+}
+
+/**
+ * Show help.
+ */
+function showHelp() {
+  console.log(`
+Quarterly Report Generator
+
+Usage:
+  npm run quarterly:report              Generate current quarter report
+  npm run quarterly:report --json       Output as JSON
+  npm run quarterly:report --verbose    Include per-skill details
+  npm run quarterly:report --status     Show current quarter status only
+  npm run quarterly:report --quarter=N  Specify quarter (1-4)
+  npm run quarterly:report --year=YYYY  Specify year
+
+Output:
+  Report saved to: ~/.claude/knowledge/reports/quarterly-Q[X]-[YEAR].md
+`);
+}
+
+/**
+ * Main entry point.
+ */
+async function main() {
+  const args = parseArgs();
+
+  if (args.help) {
+    showHelp();
+    return;
+  }
+
+  ensureDirectories();
+
+  // Determine quarter
+  const current = getCurrentQuarter();
+  const quarter = args.quarter ? parseInt(args.quarter, 10) : current.quarter;
+  const year = args.year ? parseInt(args.year, 10) : current.year;
+
+  console.log(`[Quarterly] Generating report for Q${quarter} ${year}...`);
+
+  // Load data
+  const versions = loadVersionRegistry();
+  const effectivenessData = loadEffectivenessData();
+
+  // Analyze
+  const trends = analyzeSkillTrends(effectivenessData, versions);
+  const deprecationCandidates = identifyDeprecationCandidates(effectivenessData, versions);
+  const promotionCandidates = identifyPromotionCandidates(effectivenessData);
+  const assetSummary = getAssetValueSummary();
+
+  // Generate summary
+  const summary = generateExecutiveSummary({
+    trends,
+    deprecationCandidates,
+    promotionCandidates,
+    assetSummary,
+  });
+
+  const data = {
+    quarter,
+    year,
+    generatedAt: new Date().toISOString(),
+    summary,
+    trends,
+    deprecationCandidates,
+    promotionCandidates,
+    assetSummary,
+  };
+
+  // Output
+  if (args.status) {
+    showStatus(data);
+    return;
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  // Generate and save markdown report
+  const markdown = generateMarkdownReport(data, args);
+  const reportFile = path.join(REPORTS_DIR, `quarterly-Q${quarter}-${year}.md`);
+  fs.writeFileSync(reportFile, markdown);
+
+  console.log(`[Quarterly] Report saved: ${reportFile}`);
+
+  // Also output to terminal
+  outputTerminal(data);
+}
+
+// Run
+main().catch((err) => {
+  console.error('[Quarterly] Error:', err.message);
+  process.exit(1);
+});