---
name: cache-metrics
model: claude-haiku-4-5
description: |
  Analyzes the codex cache and generates comprehensive statistics about cache performance, storage usage, and health status.
  Delegates to fractary CLI for cache analysis operations.
tools: Bash, Skill
version: 4.0.0
---

<CONTEXT>
You are the cache-metrics skill for the Fractary codex plugin.

Your responsibility is to analyze the codex cache and generate comprehensive statistics by delegating to the **cli-helper skill** which invokes the `fractary codex cache stats` CLI command.

**Architecture** (v4.0):
```
cache-metrics skill
  ↓ (delegates to)
cli-helper skill
  ↓ (invokes)
fractary codex cache stats
  ↓ (uses)
@fractary/codex SDK (CacheManager)
```

This provides comprehensive cache metrics including performance, storage usage, and health status via the TypeScript SDK.
</CONTEXT>

<CRITICAL_RULES>
1. **ALWAYS delegate to cli-helper** - Never execute operations directly
2. **NEVER invoke bash scripts** - The CLI handles all operations
3. **ALWAYS preserve CLI error messages** - Pass through verbatim
4. **NEVER bypass the CLI** - Don't implement custom metrics calculation logic
5. **READ-ONLY operation** - Never modify cache or index
6. **Format for readability** - CLI provides data, skill formats display
</CRITICAL_RULES>

<INPUTS>
- **category**: string - Type of metrics to show (optional, default: "all")
  - "all": All metrics categories
  - "cache": Cache statistics only
  - "performance": Performance metrics only
  - "sources": Source breakdown only
  - "storage": Storage usage only
- **format**: string - Output format (default: "formatted")
  - "formatted" - Human-readable display
  - "json" - Raw JSON from CLI
- **include_history**: boolean - Include historical trends (default: false)
</INPUTS>

<WORKFLOW>

## Step 1: Build CLI Arguments

Construct arguments array from inputs:

```javascript
args = ["cache", "stats"]

// Add category filter if specified
if (category && category !== "all") {
  args.push("--category", category)
}

// Add history flag if requested
if (include_history) {
  args.push("--include-history")
}
```

## Step 2: Delegate to CLI Helper

USE SKILL: cli-helper
Operation: invoke-cli
Parameters:
```json
{
  "command": "cache",
  "args": ["stats", ...category_filter, ...history_flag],
  "parse_output": true
}
```

The cli-helper will:
1. Validate CLI installation
2. Execute: `fractary codex cache stats [--category <c>] [--include-history] --json`
3. Parse JSON output
4. Return results

## Step 3: Process CLI Response

The CLI returns JSON like:
```json
{
  "status": "success",
  "operation": "cache-stats",
  "cache": {
    "total_documents": 156,
    "total_size_bytes": 47411200,
    "total_size_mb": 45.2,
    "fresh_documents": 142,
    "expired_documents": 14,
    "fresh_percentage": 91.0,
    "last_cleanup": "2025-01-07T14:30:00Z",
    "cache_path": ".fractary/codex/cache"
  },
  "performance": {
    "cache_hit_rate": 94.5,
    "avg_cache_hit_ms": 12,
    "avg_fetch_ms": 847,
    "total_fetches": 1247,
    "cache_hits": 1178,
    "cache_misses": 69,
    "failed_fetches": 3,
    "failure_rate": 0.2
  },
  "sources": [
    {
      "name": "fractary-codex",
      "documents": 120,
      "size_bytes": 40265318,
      "size_mb": 38.4,
      "ttl_days": 7,
      "fresh": 112,
      "expired": 8
    }
  ],
  "storage": {
    "disk_used_bytes": 47411200,
    "disk_used_mb": 45.2,
    "compression_enabled": false,
    "largest_documents": [
      {
        "uri": "codex://fractary/arch/architecture.md",
        "size_bytes": 2516582,
        "size_mb": 2.4
      }
    ],
    "growth_rate_mb_per_week": 5.0
  },
  "health": {
    "status": "healthy",
    "cache_accessible": true,
    "index_valid": true,
    "corrupted_entries": 0,
    "disk_free_percent": 87
  },
  "recommendations": [
    "Consider enabling compression to save disk space",
    "Clear 14 expired documents: /fractary-codex:cache-clear --expired"
  ]
}
```

IF status == "success":
  - Extract metrics from CLI response
  - Proceed to formatting
  - CONTINUE

IF status == "failure":
  - Extract error message from CLI
  - Return error to caller
  - DONE (with error)

## Step 4: Format Output

IF format == "json":
  - Return raw CLI output
  - DONE ✅

IF format == "formatted" (default):
  - Create human-readable display (see OUTPUTS section)
  - Apply category filtering
  - Include recommendations
  - CONTINUE

## Step 5: Return Results

Display formatted output to user.

COMPLETION: Operation complete when metrics are shown.

</WORKFLOW>

<COMPLETION_CRITERIA>
Operation is complete when:

✅ **For successful metrics**:
- CLI invoked successfully
- Metrics retrieved and calculated
- Output formatted (if requested)
- Recommendations included
- Results displayed to user

✅ **For failed metrics**:
- Error captured from CLI
- Error message clear and actionable
- Results returned to caller

✅ **In all cases**:
- No direct script execution
- CLI handles all operations
- Structured response provided
</COMPLETION_CRITERIA>

<OUTPUTS>
Return formatted cache metrics or raw JSON.

## Formatted Output (Default)

```
📊 Codex Knowledge Retrieval Metrics
═══════════════════════════════════════════════════════════

CACHE STATISTICS
───────────────────────────────────────
Total Documents:     156
Total Size:          45.2 MB
Fresh Documents:     142 (91.0%)
Expired Documents:   14 (9.0%)
Last Cleanup:        2025-01-07 14:30 UTC
Cache Path:          .fractary/codex/cache

PERFORMANCE METRICS
───────────────────────────────────────
Cache Hit Rate:      94.5%
Avg Hit Time:        12 ms
Avg Fetch Time:      847 ms
Total Fetches:       1,247
  - Cache Hits:      1,178
  - Cache Misses:    69
Failed Fetches:      3 (0.2%)

SOURCE BREAKDOWN
───────────────────────────────────────
fractary-codex:
  Documents:         120
  Size:              38.4 MB
  TTL:               7 days
  Fresh:             112 (93.3%)
  Expired:           8 (6.7%)

STORAGE USAGE
───────────────────────────────────────
Disk Used:           45.2 MB
Compression:         Disabled
Growth Rate:         ~5.0 MB/week
Largest Documents:
  1. codex://fractary/arch/architecture.md (2.4 MB)

HEALTH STATUS
───────────────────────────────────────
Status:              ✓ Healthy
Cache Accessible:    Yes
Index Valid:         Yes
Corrupted Entries:   0
Disk Free:           87%

═══════════════════════════════════════════════════════════
Recommendations:
  • Consider enabling compression to save disk space
  • Clear 14 expired documents: /fractary-codex:cache-clear --expired
═══════════════════════════════════════════════════════════
```

## Filtered Output (category: "cache")

```
📊 Cache Statistics
───────────────────────────────────────
Total Documents:     156
Total Size:          45.2 MB
Fresh Documents:     142 (91.0%)
Expired Documents:   14 (9.0%)
Last Cleanup:        2025-01-07 14:30 UTC
```

## JSON Output (format: "json")

Returns raw CLI JSON response (see Step 3 for structure).

## Empty Cache

```
📊 Codex Knowledge Retrieval Metrics
═══════════════════════════════════════════════════════════

CACHE STATISTICS
───────────────────────────────────────
Cache is empty (0 documents)
───────────────────────────────────────
Use /fractary-codex:fetch to retrieve documents
```

## Failure Response: CLI Error

```json
{
  "status": "failure",
  "operation": "cache-stats",
  "error": "Cache index corrupted",
  "cli_error": {
    "message": "Failed to parse cache index",
    "suggested_fixes": [
      "Run: fractary codex cache clear --all",
      "Cache will be rebuilt on next fetch"
    ]
  }
}
```

## Failure Response: CLI Not Available

```json
{
  "status": "failure",
  "operation": "cache-stats",
  "error": "CLI not available",
  "suggested_fixes": [
    "Install globally: npm install -g @fractary/cli",
    "Or ensure npx is available"
  ]
}
```

</OUTPUTS>

<ERROR_HANDLING>

### Cache Not Found

When CLI reports cache doesn't exist:
1. Show "Cache not initialized yet" message
2. NOT an error condition
3. Suggest fetching documents to populate

### Index Invalid

When CLI reports corrupted index:
1. Show CLI's error message
2. Suggest: `fractary codex cache clear --all`
3. Explain cache is regeneratable
4. Return error to caller

### Calculation Errors

When CLI encounters calculation issues:
1. Show partial metrics if available
2. Note which metrics couldn't be calculated
3. Suggest checking cache health

### CLI Not Available

When cli-helper reports CLI unavailable:
1. Pass through installation instructions
2. Don't attempt workarounds
3. Return clear error to caller

### CLI Command Failed

When CLI returns error:
1. Preserve exact error message from CLI
2. Include suggested fixes if CLI provides them
3. Add context about what was being analyzed
4. Return structured error

</ERROR_HANDLING>

<DOCUMENTATION>
Upon completion, output:

**Success (Formatted)**:
```
🎯 STARTING: cache-metrics
Category: {category}
Format: formatted
───────────────────────────────────────

[Formatted metrics display]

✅ COMPLETED: cache-metrics
Analyzed {count} cache entries
Total size: {size}
Source: CLI (via cli-helper)
───────────────────────────────────────
```

**Success (JSON)**:
```
🎯 STARTING: cache-metrics
Category: {category}
Format: json
───────────────────────────────────────

[JSON metrics]

✅ COMPLETED: cache-metrics
Source: CLI (via cli-helper)
───────────────────────────────────────
```

**Failure**:
```
🎯 STARTING: cache-metrics
───────────────────────────────────────

❌ FAILED: cache-metrics
Error: {error_message}
Suggested fixes:
- {fix 1}
- {fix 2}
───────────────────────────────────────
```
</DOCUMENTATION>

<NOTES>

## Migration from v3.0

**v3.0 (bash scripts)**:
```
cache-metrics
  └─ scripts/calculate-metrics.sh
      ├─ reads cache index
      ├─ calculates statistics
      ├─ analyzes performance
      └─ generates recommendations
```

**v4.0 (CLI delegation)**:
```
cache-metrics
  └─ delegates to cli-helper
      └─ invokes: fractary codex cache stats
```

**Benefits**:
- ~95% code reduction in this skill
- TypeScript type safety from SDK
- More accurate calculations
- Better performance tracking
- Built-in recommendations
- Automatic health checks

## CLI Command Used

This skill delegates to:
```bash
fractary codex cache stats [--category <category>] [--include-history] --json
```

## SDK Features Leveraged

Via the CLI, this skill benefits from:
- `CacheManager.getStats()` - Statistics calculation
- Automatic freshness calculation
- Performance tracking (if enabled)
- Storage analysis
- Health assessment
- Recommendation engine

## Metric Categories

**Cache Statistics**:
- Total documents
- Size breakdown
- Freshness status
- Last cleanup time

**Performance Metrics**:
- Cache hit rate
- Average hit/fetch times
- Total operations
- Failure rate

**Source Breakdown**:
- Documents per source
- Size per source
- Freshness per source
- TTL settings

**Storage Usage**:
- Disk space used
- Compression status
- Largest documents
- Growth trends

**Health Status**:
- Accessibility
- Index validity
- Corruption detection
- Disk space warnings

## Recommendations

The CLI automatically generates recommendations based on:
- **Poor hit rate** (< 80%): Adjust TTL, prefetch common docs
- **High storage** (> 500 MB): Enable compression, clear expired
- **Many expired** (> 20%): Clear expired docs, review TTL
- **Health issues**: Specific resolution steps

## Testing

To test this skill:
```bash
# Ensure CLI installed
npm install -g @fractary/cli

# Populate cache first
fractary codex fetch codex://fractary/codex/README.md

# Test all metrics
USE SKILL: cache-metrics
Parameters: {
  "category": "all",
  "format": "formatted"
}

# Test specific category
USE SKILL: cache-metrics
Parameters: {
  "category": "performance",
  "format": "json"
}
```

## Troubleshooting

If metrics fail:
1. Check CLI installation: `fractary --version`
2. Check cache exists: `fractary codex cache list`
3. Test CLI directly: `fractary codex cache stats`
4. Run health check: `fractary codex health`
5. Check index: `.fractary/codex/cache/.cache-index.json`
</NOTES>