cache-health

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

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.

<CRITICAL_RULES>

ALWAYS delegate to cli-helper - Never execute operations directly
NEVER invoke bash scripts - The CLI handles all operations
ALWAYS preserve CLI error messages - Pass through verbatim
NEVER bypass the CLI - Don't implement custom health check logic
READ-ONLY by default - Only modify with --fix flag
LOG all fixes - Document repair operations clearly </CRITICAL_RULES>

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.

<COMPLETION_CRITERIA> 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 </COMPLETION_CRITERIA>

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"
  ]
}

<ERROR_HANDLING>

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

</ERROR_HANDLING>

<DOCS_MANAGE_AUDIT_INTEGRATION>

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 </DOCS_MANAGE_AUDIT_INTEGRATION>

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

$ Instalar