Initial commit

skills/nav-stats/functions/efficiency_scorer.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+Calculate Navigator efficiency score (0-100).
+
+Weights:
+- Token savings: 40 points (85%+ = max)
+- Cache efficiency: 30 points (100% = max)
+- Context usage: 30 points (<40% = max, >80% = 0)
+"""
+
+import sys
+import argparse
+
+def calculate_efficiency_score(
+    tokens_saved_percent: float,
+    cache_efficiency: float,
+    context_usage_percent: float
+) -> int:
+    """
+    Calculate Navigator efficiency score (0-100).
+
+    Args:
+        tokens_saved_percent: Percentage of tokens saved vs baseline (0-100)
+        cache_efficiency: Cache hit rate (0-100)
+        context_usage_percent: Percentage of context window used (0-100)
+
+    Returns:
+        int: Efficiency score (0-100)
+    """
+    # Token savings (40 points max)
+    # 85%+ savings = 40 points, linear scale below
+    token_score = min(40, (tokens_saved_percent / 85) * 40)
+
+    # Cache efficiency (30 points max)
+    # 100% = 30 points, linear scale
+    cache_score = (cache_efficiency / 100) * 30
+
+    # Context usage (30 points max)
+    # <40% = 30 points (excellent)
+    # 40-80% = linear from 30 to 0 (good → fair)
+    # >80% = 0 points (poor - context overloaded)
+    if context_usage_percent < 40:
+        context_score = 30
+    elif context_usage_percent <= 80:
+        # Linear decay from 30 (at 40%) to 0 (at 80%)
+        context_score = 30 - ((context_usage_percent - 40) / 40) * 30
+    else:
+        context_score = 0
+
+    total_score = int(token_score + cache_score + context_score)
+
+    # Ensure score is in valid range
+    return max(0, min(100, total_score))
+
+def interpret_score(score: int) -> str:
+    """
+    Interpret efficiency score into human-readable rating.
+
+    Args:
+        score: Efficiency score (0-100)
+
+    Returns:
+        str: Rating (excellent, good, fair, poor)
+    """
+    if score >= 90:
+        return "excellent"
+    elif score >= 80:
+        return "good"
+    elif score >= 70:
+        return "fair"
+    else:
+        return "poor"
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Calculate Navigator efficiency score"
+    )
+    parser.add_argument(
+        "--tokens-saved-percent",
+        type=float,
+        required=True,
+        help="Percentage of tokens saved vs baseline (0-100)"
+    )
+    parser.add_argument(
+        "--cache-efficiency",
+        type=float,
+        required=True,
+        help="Cache hit rate percentage (0-100)"
+    )
+    parser.add_argument(
+        "--context-usage",
+        type=float,
+        required=True,
+        help="Context window usage percentage (0-100)"
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show detailed breakdown"
+    )
+
+    args = parser.parse_args()
+
+    score = calculate_efficiency_score(
+        args.tokens_saved_percent,
+        args.cache_efficiency,
+        args.context_usage
+    )
+
+    if args.verbose:
+        rating = interpret_score(score)
+        print(f"Efficiency Score: {score}/100 ({rating})")
+        print(f"  Token savings: {args.tokens_saved_percent}%")
+        print(f"  Cache efficiency: {args.cache_efficiency}%")
+        print(f"  Context usage: {args.context_usage}%")
+    else:
+        # Output just the score (parseable)
+        print(score)
+
+    sys.exit(0)

skills/nav-stats/functions/report_formatter.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""
+Format Navigator efficiency metrics into visual, shareable report.
+"""
+
+import sys
+import argparse
+
+def format_number(num: int) -> str:
+    """Format number with commas for readability."""
+    return f"{num:,}"
+
+def interpret_score(score: int) -> str:
+    """Get rating label for score."""
+    if score >= 90:
+        return "excellent"
+    elif score >= 80:
+        return "good"
+    elif score >= 70:
+        return "fair"
+    else:
+        return "poor"
+
+def get_recommendations(
+    savings_percent: int,
+    cache_efficiency: float,
+    context_usage: int,
+    efficiency_score: int
+) -> list:
+    """
+    Generate actionable recommendations based on metrics.
+
+    Returns:
+        list: List of recommendation strings
+    """
+    recs = []
+
+    # Check token savings
+    if savings_percent < 70:
+        recs.append(("⚠️", "Token savings below target (70%+)"))
+        recs.append(("→", "Check: Are you loading more docs than needed?"))
+        recs.append(("→", "Tip: Use navigator to find docs, don't load all upfront"))
+        recs.append(("", "Read more: .agent/philosophy/CONTEXT-EFFICIENCY.md"))
+    elif savings_percent >= 85:
+        recs.append(("✅", "Excellent token savings - keep using lazy-loading strategy"))
+
+    # Check cache efficiency
+    if cache_efficiency < 80:
+        recs.append(("⚠️", "Cache efficiency low (<80%)"))
+        recs.append(("→", "Check: CLAUDE.md properly configured?"))
+        recs.append(("→", "Tip: Ensure prompt caching enabled"))
+        recs.append(("", "Read more: .agent/philosophy/PATTERNS.md (Caching pattern)"))
+    elif cache_efficiency >= 95:
+        recs.append(("✅", "Cache working perfectly - no optimization needed"))
+
+    # Check context usage
+    if context_usage > 80:
+        recs.append(("⚠️", "Context usage high (80%+)"))
+        recs.append(("→", "Consider: Create context marker and compact"))
+        recs.append(("→", "Tip: Compact after completing sub-tasks"))
+        recs.append(("", "Read more: .agent/philosophy/ANTI-PATTERNS.md"))
+    elif context_usage < 40:
+        recs.append(("✅", "Context usage healthy - plenty of room for work"))
+
+    # Default excellent message
+    if not recs and efficiency_score >= 90:
+        recs.append(("✅", "Excellent efficiency - keep it up!"))
+        recs.append(("", ""))
+        recs.append(("", "Share your efficiency: Take a screenshot! #ContextEfficiency"))
+
+    return recs
+
+def format_report(
+    baseline: int,
+    loaded: int,
+    saved: int,
+    savings_percent: int,
+    cache_efficiency: float,
+    context_usage: int,
+    efficiency_score: int,
+    time_saved: int
+) -> str:
+    """
+    Format efficiency report.
+
+    Returns:
+        str: Formatted report
+    """
+    rating = interpret_score(efficiency_score)
+    recs = get_recommendations(savings_percent, cache_efficiency, context_usage, efficiency_score)
+
+    report = f"""╔══════════════════════════════════════════════════════╗
+║          NAVIGATOR EFFICIENCY REPORT                 ║
+╚══════════════════════════════════════════════════════╝
+
+📊 TOKEN USAGE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Documentation loaded:    {format_number(loaded):>12} tokens
+Baseline (all docs):     {format_number(baseline):>12} tokens
+Tokens saved:            {format_number(saved):>12} tokens ({savings_percent}% ↓)
+
+💾 CACHE PERFORMANCE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Cache efficiency:        {cache_efficiency:>16.1f}% ({"perfect" if cache_efficiency >= 99 else "good" if cache_efficiency >= 90 else "fair"})
+
+📈 SESSION METRICS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Context usage:           {context_usage:>16}% ({rating})
+Efficiency score:        {efficiency_score:>12}/100 ({rating})
+
+⏱️  TIME SAVED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Estimated time saved:    {time_saved:>13} minutes
+
+💡 WHAT THIS MEANS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Navigator loaded {savings_percent}% fewer tokens than loading all docs.
+Your context window is {100 - context_usage}% available for actual work.
+"""
+
+    # Add recommendations section
+    if recs:
+        report += "\n🎯 RECOMMENDATIONS\n"
+        report += "━" * 54 + "\n"
+        for icon, text in recs:
+            if icon:
+                report += f"{icon}  {text}\n"
+            else:
+                report += f"{text}\n"
+
+    return report
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Format Navigator efficiency report"
+    )
+    parser.add_argument("--baseline", type=int, required=True, help="Baseline tokens (all docs)")
+    parser.add_argument("--loaded", type=int, required=True, help="Actually loaded tokens")
+    parser.add_argument("--saved", type=int, required=True, help="Tokens saved")
+    parser.add_argument("--savings-percent", type=int, required=True, help="Savings percentage")
+    parser.add_argument("--cache-efficiency", type=float, required=True, help="Cache efficiency %")
+    parser.add_argument("--context-usage", type=int, required=True, help="Context usage %")
+    parser.add_argument("--efficiency-score", type=int, required=True, help="Efficiency score (0-100)")
+    parser.add_argument("--time-saved", type=int, required=True, help="Time saved (minutes)")
+
+    args = parser.parse_args()
+
+    report = format_report(
+        args.baseline,
+        args.loaded,
+        args.saved,
+        args.savings_percent,
+        args.cache_efficiency,
+        args.context_usage,
+        args.efficiency_score,
+        args.time_saved
+    )
+
+    print(report)
+    sys.exit(0)