nav-stats

What this skill does

# Navigator Session Statistics Skill

Show real-time efficiency reporting with baseline comparisons, making Navigator's value quantifiable and shareable.

## When to Invoke

Invoke this skill when the user:
- Says "show my stats", "show session stats", "show metrics"
- Asks "how efficient am I?", "how much did I save?"
- Says "show my Navigator report", "efficiency report"
- Wants to see token savings or session performance
- Says "show impact", "prove Navigator works"

**DO NOT invoke** if:
- User just started session (< 5 messages)
- Navigator not initialized in project
- User asking about specific metrics only (answer directly)

## Execution Steps

### Step 1: Check Navigator Initialized

Verify Navigator is set up:

```bash
if [ ! -f ".agent/DEVELOPMENT-README.md" ]; then
  echo "❌ Navigator not initialized in this project"
  echo "Run 'Initialize Navigator' first"
  exit 1
fi
```

### Step 2: Run Enhanced Session Stats

Execute the enhanced session statistics script:

```bash
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"

# Check if enhanced script exists
if [ ! -f "$PLUGIN_DIR/scripts/session-stats.sh" ]; then
  echo "❌ Session stats script not found"
  echo "Reinstall or update Navigator to restore scripts/session-stats.sh"
  exit 1
fi

# Run stats script
bash "$PLUGIN_DIR/scripts/session-stats.sh"
```

This script outputs shell-parseable variables:
- `BASELINE_TOKENS` - Total size of all .agent/ docs
- `LOADED_TOKENS` - Actually loaded in session (estimated)
- `TOKENS_SAVED` - Difference
- `SAVINGS_PERCENT` - Percentage saved
- `EFFICIENCY_SCORE` - 0-100 score
- `CACHE_EFFICIENCY` - From OpenTelemetry
- `CONTEXT_USAGE_PERCENT` - Estimated context fill
- `TIME_SAVED_MINUTES` - Estimated time saved

### Step 3: Calculate Efficiency Score

Use predefined function to calculate score:

```bash
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"

# Extract metrics from session-stats.sh
source <(bash "$PLUGIN_DIR/scripts/session-stats.sh")

# Calculate efficiency score using predefined function
EFFICIENCY_SCORE=$(python3 "$PLUGIN_DIR/skills/nav-stats/functions/efficiency_scorer.py" \
  --tokens-saved-percent ${SAVINGS_PERCENT} \
  --cache-efficiency ${CACHE_EFFICIENCY} \
  --context-usage ${CONTEXT_USAGE_PERCENT})
```

### Step 4: Format and Display Report

Use predefined function to format visual report:

```bash
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"

# Generate formatted report
python3 "$PLUGIN_DIR/skills/nav-stats/functions/report_formatter.py" \
  --baseline ${BASELINE_TOKENS} \
  --loaded ${LOADED_TOKENS} \
  --saved ${TOKENS_SAVED} \
  --savings-percent ${SAVINGS_PERCENT} \
  --cache-efficiency ${CACHE_EFFICIENCY} \
  --context-usage ${CONTEXT_USAGE_PERCENT} \
  --efficiency-score ${EFFICIENCY_SCORE} \
  --time-saved ${TIME_SAVED_MINUTES}
```

**Output Format**:
```
╔══════════════════════════════════════════════════════╗
║          NAVIGATOR EFFICIENCY REPORT                 ║
╚══════════════════════════════════════════════════════╝

📊 TOKEN USAGE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Documentation loaded:        12,000 tokens
Baseline (all docs):        150,000 tokens
Tokens saved:               138,000 tokens (92% ↓)

💾 CACHE PERFORMANCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Cache efficiency:              100.0% (perfect)

📈 SESSION METRICS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Context usage:                      35% (excellent)
Efficiency score:                94/100 (excellent)

⏱️  TIME SAVED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Estimated time saved:          ~42 minutes

💡 WHAT THIS MEANS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Navigator loaded 92% fewer tokens than loading all docs.
Your context window is 65% available for actual work.

🎯 RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Excellent efficiency - keep using lazy-loading strategy
✅ Context usage healthy - plenty of room for work

Share your efficiency: Take a screenshot! #ContextEfficiency
```

### Step 5: Add Context-Specific Recommendations

Based on efficiency score, provide actionable advice:

**If efficiency_score < 70**:
```
⚠️  RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  Token savings below target (70%+)
→ Check: Are you loading more docs than needed?
→ Tip: Use navigator to find docs, don't load all upfront

Read more: .agent/philosophy/CONTEXT-EFFICIENCY.md
```

**If context_usage > 80%**:
```
⚠️  RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  Context usage high (80%+)
→ Consider: Create context marker and compact
→ Tip: Compact after completing sub-tasks

Read more: .agent/philosophy/ANTI-PATTERNS.md
```

**If cache_efficiency < 80%**:
```
⚠️  RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  Cache efficiency low (<80%)
→ Check: CLAUDE.md properly configured?
→ Tip: Ensure prompt caching enabled

Read more: .agent/philosophy/PATTERNS.md (Caching pattern)
```

## Predefined Functions

### `efficiency_scorer.py`

Calculate Navigator efficiency score (0-100) based on:
- Token savings (40 points)
- Cache efficiency (30 points)
- Context usage (30 points)

**Usage**:
```bash
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"

python3 "$PLUGIN_DIR/skills/nav-stats/functions/efficiency_scorer.py" \
  --tokens-saved-percent 92 \
  --cache-efficiency 100 \
  --context-usage 35
```

**Output**: `94` (integer score)

### `report_formatter.py`

Format efficiency metrics into visual, shareable report.

**Usage**:
```bash
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"

python3 "$PLUGIN_DIR/skills/nav-stats/functions/report_formatter.py" \
  --baseline 150000 \
  --loaded 12000 \
  --saved 138000 \
  --savings-percent 92 \
  --cache-efficiency 100 \
  --context-usage 35 \
  --efficiency-score 94 \
  --time-saved 42
```

**Output**: Formatted ASCII report (see Step 4)

## Philosophy Integration

**Context Engineering Principle**: Measurement validates optimization

From `.agent/philosophy/PATTERNS.md`:
> "Measure to validate. Navigator tracks real metrics, not estimates."

This skill proves:
- **Token savings** are real (baseline comparison)
- **Cache efficiency** works (OpenTelemetry data)
- **Context usage** is healthy (window not overloaded)
- **Time saved** is quantifiable (6s per 1k tokens)

## User Experience

**User says**: "Show my stats"

**Skill displays**:
1. Visual efficiency report
2. Clear metrics (tokens, cache, context)
3. Interpretation ("What this means")
4. Actionable recommendations

**User can**:
- Screenshot and share (#ContextEfficiency)
- Understand Navigator's impact
- Optimize workflow based on recommendations
- Validate context engineering principles

## Example Output Scenarios

### Scenario 1: Excellent Efficiency (Score 94)

User following lazy-loading pattern, cache working perfectly:
- 92% token savings ✅
- 100% cache efficiency ✅
- 35% context usage ✅
- Score: 94/100

**Recommendation**: Keep it up! Share your efficiency.

### Scenario 2: Fair Efficiency (Score 72)

User loading too many docs upfront:
- 65% token savings ⚠️
- 95% cache efficiency ✅
- 55% context usage ✅
- Score: 72/100

**Recommendation**: Review lazy-loading strategy. Load docs on-demand.

### Scena