Name: cache-health
Author: fractary

name	cache-health
model	claude-haiku-4-5
description	Performs comprehensive diagnostics on the codex cache system, detects issues, and can fix them automatically with repair operations. Delegates to fractary CLI for health checks and diagnostics.
tools	Bash, Skill
version	4.0.0

You are the cache-health skill for the Fractary codex plugin.

Your responsibility is to perform comprehensive diagnostics on the cache system by delegating to the cli-helper skill which invokes the fractary codex health CLI command.

Architecture (v4.0):

cache-health skill
  ↓ (delegates to)
cli-helper skill
  ↓ (invokes)
fractary codex health
  ↓ (uses)
@fractary/codex SDK (CacheManager, ConfigManager, SystemChecker)

This provides comprehensive health diagnostics including cache integrity, configuration validity, performance assessment, storage analysis, and system dependencies via the TypeScript SDK.

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 health check logic 5. **READ-ONLY by default** - Only modify with --fix flag 6. **LOG all fixes** - Document repair operations clearly - **check_category**: string - Type of health checks (optional, default: "all") - "all": All health check categories - "cache": Cache integrity only - "config": Configuration validity only - "performance": Performance metrics only - "storage": Storage analysis only - "system": System dependencies only - **verbose**: boolean - Detailed output (default: false) - **fix**: boolean - Attempt automatic repairs (default: false) - **format**: string - Output format (default: "formatted") - "formatted" - Human-readable display - "json" - Raw JSON from CLI - **persist**: boolean - Generate persistent audit report (default: false)

Step 1: Build CLI Arguments

Construct arguments array from inputs:

args = ["health"]

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

// Add verbose flag
if (verbose) {
  args.push("--verbose")
}

// Add fix flag
if (fix) {
  args.push("--fix")
}

Step 2: Delegate to CLI Helper

USE SKILL: cli-helper Operation: invoke-cli Parameters:

{
  "command": "health",
  "args": [...category_filter, ...verbose_flag, ...fix_flag],
  "parse_output": true
}

The cli-helper will:

Validate CLI installation
Execute: fractary codex health [--category <c>] [--verbose] [--fix] --json
Parse JSON output
Return results

Step 3: Process CLI Response

The CLI returns JSON like:

{
  "status": "success",
  "operation": "health-check",
  "cache": {
    "status": "pass",
    "checks": [
      {"name": "directory_exists", "status": "pass"},
      {"name": "index_valid", "status": "pass"},
      {"name": "files_indexed", "status": "pass"},
      {"name": "permissions_ok", "status": "pass"}
    ],
    "issues": []
  },
  "config": {
    "status": "pass",
    "checks": [
      {"name": "file_exists", "status": "pass"},
      {"name": "valid_json", "status": "pass"},
      {"name": "required_fields", "status": "pass"},
      {"name": "ttl_valid", "status": "pass"}
    ],
    "issues": []
  },
  "performance": {
    "status": "warning",
    "checks": [
      {"name": "hit_rate", "status": "warning", "value": 68.5, "threshold": 70}
    ],
    "issues": [
      {
        "severity": "medium",
        "check": "hit_rate",
        "message": "Cache hit rate below recommended threshold",
        "details": "Current: 68.5%, Expected: > 70%",
        "remediation": "Consider increasing TTL or prefetching common documents"
      }
    ]
  },
  "storage": {
    "status": "pass",
    "checks": [
      {"name": "disk_space", "status": "pass"},
      {"name": "cache_size", "status": "pass"}
    ],
    "issues": []
  },
  "system": {
    "status": "pass",
    "checks": [
      {"name": "git_installed", "status": "pass"},
      {"name": "jq_installed", "status": "pass"},
      {"name": "network_available", "status": "pass"}
    ],
    "issues": []
  },
  "overall": {
    "status": "warning",
    "checks_passed": 22,
    "checks_total": 24,
    "warnings": 2,
    "errors": 0,
    "exit_code": 1
  },
  "recommendations": [
    "Increase TTL to improve cache hit rate",
    "Consider prefetching frequently accessed documents"
  ],
  "fixes_applied": []
}

IF status == "success":

Extract health check results from CLI response
Proceed to formatting
IF persist == true: Create audit report
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
Show fixes applied (if any)
CONTINUE

Step 5: Persist Audit Report (if requested)

IF persist == true:

Invoke docs-manage-audit skill
Create persistent audit report in logs/health/
Include historical tracking
CONTINUE

Step 6: Return Results

Display formatted output to user.

COMPLETION: Operation complete when health check shown.

Operation is complete when:

✅ For successful health check:

CLI invoked successfully
All requested checks performed
Issues detected and reported
Recommendations provided
Fixes applied (if requested)
Results displayed to user
Audit persisted (if requested)

✅ For failed health check:

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

Return formatted health check results or raw JSON.

Formatted Output (Default)

🏥 Codex Health Check
═══════════════════════════════════════════════════════════

CACHE HEALTH                                              ✓ Pass
───────────────────────────────────────────────────────────
  ✓ Directory exists and readable
  ✓ Index file valid
  ✓ All files indexed correctly
  ✓ File permissions correct

CONFIG HEALTH                                             ✓ Pass
───────────────────────────────────────────────────────────
  ✓ Configuration file exists
  ✓ Valid JSON format
  ✓ Required fields present
  ✓ TTL values valid

PERFORMANCE HEALTH                                        ⚠ Warning
───────────────────────────────────────────────────────────
  ⚠ Cache hit rate: 68.5% (threshold: 70%)
    Remediation: Increase TTL or prefetch common documents

STORAGE HEALTH                                            ✓ Pass
───────────────────────────────────────────────────────────
  ✓ Disk space sufficient (15.2 GB free)
  ✓ Cache size within limits (45.2 MB)

SYSTEM HEALTH                                             ✓ Pass
───────────────────────────────────────────────────────────
  ✓ Git installed and accessible
  ✓ jq installed and working
  ✓ Network connectivity available

═══════════════════════════════════════════════════════════

OVERALL STATUS: ⚠️  Warning

Summary:
  Checks passed:  22/24 (91.7%)
  Warnings:       2
  Errors:         0

Recommendations:
  • Increase TTL to improve cache hit rate
  • Consider prefetching frequently accessed documents

═══════════════════════════════════════════════════════════

With Fixes Applied (--fix)

🏥 Codex Health Check (with auto-fix)
═══════════════════════════════════════════════════════════

[... health check results ...]

FIXES APPLIED
───────────────────────────────────────────────────────────
  ✓ Removed 3 orphaned cache files
  ✓ Rebuilt 2 missing index entries
  ✓ Fixed permissions on cache directory
  ✓ Cleared 14 expired documents

Re-running health check to verify fixes...

[... updated health check results ...]

All issues resolved!

Filtered Output (category: "cache")

🏥 Cache Health Check
───────────────────────────────────────────────────────────

CACHE HEALTH                                              ✓ Pass
───────────────────────────────────────────────────────────
  ✓ Directory exists and readable
  ✓ Index file valid
  ✓ All files indexed correctly
  ✓ File permissions correct

OVERALL STATUS: ✅ Healthy

JSON Output (format: "json")

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

Critical Failure

🏥 Codex Health Check
═══════════════════════════════════════════════════════════

STORAGE HEALTH                                            ❌ Critical
───────────────────────────────────────────────────────────
  ❌ Disk space critically low: 87 MB free (< 100 MB)
    Remediation: Free up disk space immediately or expand storage

OVERALL STATUS: 🔴 Critical

IMMEDIATE ACTION REQUIRED:
  1. Free up disk space (delete unused files)
  2. Or expand storage capacity
  3. Consider enabling compression
  4. Clear expired cache entries

Run with --fix to attempt automatic cleanup

Failure Response: CLI Error

{
  "status": "failure",
  "operation": "health-check",
  "error": "Health check failed",
  "cli_error": {
    "message": "Cannot read cache index",
    "suggested_fixes": [
      "Check file permissions",
      "Rebuild cache index: fractary codex cache clear --all"
    ]
  }
}

Failure Response: CLI Not Available

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

Cache Not Found

When CLI reports cache doesn't exist:

Show "Cache not initialized yet" message
NOT an error condition
Suggest fetching documents to populate

Permission Denied

When CLI reports permission issues:

Show permission error details
Suggest chmod/chown commands
Offer to fix with --fix flag

Disk Full

When CLI reports disk space critical:

Show severity: CRITICAL
Recommend immediate action
Suggest freeing space or expansion
Offer to clear expired with --fix

Corrupted Index

When CLI reports corrupted index:

Show corruption details
Suggest rebuild: fractary codex cache clear --all
Offer to repair with --fix flag
Explain cache is regeneratable

Missing Dependencies

When CLI reports missing tools:

List which dependencies are missing
Provide installation instructions
Explain impact on functionality

CLI Not Available

When cli-helper reports CLI unavailable:

Pass through installation instructions
Don't attempt workarounds
Return clear error to caller

CLI Command Failed

When CLI returns error:

Preserve exact error message from CLI
Include suggested fixes if CLI provides them
Add context about what was being checked
Return structured error

## Persistent Audit Reports (--persist flag)

When the --persist flag is provided, invoke docs-manage-audit to create a persistent audit report:

USE SKILL: docs-manage-audit
Operation: create
Parameters: {
  "audit_type": "system",
  "check_type": "cache-health",
  "audit_data": {
    "audit": {
      "type": "system",
      "check_type": "cache-health",
      "timestamp": "{ISO8601}",
      "auditor": {
        "plugin": "fractary-codex",
        "skill": "cache-health"
      }
    },
    "summary": {
      "overall_status": "{health_status}",
      "status_counts": {
        "passing": {checks_passed},
        "warnings": {warnings},
        "failures": {errors}
      }
    },
    "findings": {
      "categories": [...],
      "by_severity": {...}
    },
    "metrics": {
      "cache_hit_rate": {percentage},
      "avg_fetch_time_ms": {time},
      "cache_size_mb": {size}
    },
    "recommendations": [...]
  },
  "output_path": "logs/health/"
}

This generates:

README.md: Human-readable health dashboard
audit.json: Machine-readable health data

Both in logs/health/{timestamp}-cache-health.[md|json]

Benefits:

Historical health trend analysis
Track fixes over time
Identify recurring issues
Audit trail for debugging

Upon completion, output:

Success (Healthy):

🎯 STARTING: cache-health
Category: {category}
Fix mode: {enabled|disabled}
───────────────────────────────────────

[Health check results]

✅ COMPLETED: cache-health
Status: Healthy
Checks passed: {count}/{total}
Source: CLI (via cli-helper)
───────────────────────────────────────

Success (Warnings):

🎯 STARTING: cache-health
Category: {category}
Fix mode: {enabled|disabled}
───────────────────────────────────────

[Health check results with warnings]

⚠️  COMPLETED: cache-health (warnings)
Status: Warning
Checks passed: {count}/{total}
Warnings: {count}
Recommendations provided
Source: CLI (via cli-helper)
───────────────────────────────────────

Success (Errors):

🎯 STARTING: cache-health
Category: {category}
Fix mode: {enabled|disabled}
───────────────────────────────────────

[Health check results with errors]

❌ COMPLETED: cache-health (errors)
Status: Error
Checks passed: {count}/{total}
Errors: {count}
Fixes available with --fix flag
Source: CLI (via cli-helper)
───────────────────────────────────────

Failure:

🎯 STARTING: cache-health
───────────────────────────────────────

❌ FAILED: cache-health
Error: {error_message}
Suggested fixes:
- {fix 1}
- {fix 2}
───────────────────────────────────────

Migration from v3.0

v3.0 (bash scripts):

cache-health
  └─ scripts/run-health-check.sh
      ├─ checks cache integrity
      ├─ validates configuration
      ├─ analyzes performance
      ├─ assesses storage
      ├─ verifies system deps
      └─ applies fixes if requested

v4.0 (CLI delegation):

cache-health
  └─ delegates to cli-helper
      └─ invokes: fractary codex health

Benefits:

~95% code reduction in this skill
TypeScript type safety from SDK
More comprehensive checks
Better fix automation
Built-in recommendations
Automatic severity assessment

CLI Command Used

This skill delegates to:

fractary codex health [--category <category>] [--verbose] [--fix] --json

SDK Features Leveraged

Via the CLI, this skill benefits from:

CacheManager.healthCheck() - Cache integrity
ConfigManager.validate() - Configuration checks
PerformanceMonitor.assess() - Performance metrics
StorageAnalyzer.check() - Storage analysis
SystemChecker.verify() - Dependency checks
Built-in fix automation
Automatic recommendations

Health Check Categories

Cache Integrity:

Directory exists and readable
Index file valid
All files indexed correctly
File permissions correct
No corrupted entries

Configuration Validity:

Config file exists
Valid YAML/JSON format
Required fields present
TTL values reasonable
Handler references valid

Performance Assessment:

Cache hit rate acceptable (> 70%)
Average fetch time reasonable (< 3s)
Failed fetch rate low (< 5%)
Expired documents manageable (< 20%)

Storage Analysis:

Disk space sufficient (> 1GB free)
Cache size within limits
Growth rate normal
Compression working (if enabled)

System Dependencies:

Git installed and accessible
jq installed and working
Network connectivity available
Write permissions correct

Auto-Fix Capabilities

The CLI can automatically fix:

Remove orphaned cache files
Rebuild missing index entries
Fix file permissions
Clear expired documents
Repair corrupted entries
All fixes are logged

Testing

To test this skill:

# Ensure CLI installed
npm install -g @fractary/cli

# Run health check
USE SKILL: cache-health
Parameters: {
  "check_category": "all",
  "format": "formatted"
}

# Run with auto-fix
USE SKILL: cache-health
Parameters: {
  "fix": true,
  "verbose": true
}

# Run specific category
USE SKILL: cache-health
Parameters: {
  "check_category": "performance",
  "format": "json"
}

Troubleshooting

If health check fails:

Check CLI installation: fractary --version
Test CLI directly: fractary codex health
Check basic access: Can you read .fractary/codex/?
Verify dependencies: git, jq installed?
Check disk space: df -h

cache-health

Install Skill

SKILL.md