cache-health

<CONTEXT> 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. </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 health check logic
5. READ-ONLY by default - Only modify with --fix flag
6. LOG all fixes - Document repair operations clearly </CRITICAL_RULES>

<INPUTS> - **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) </INPUTS> <WORKFLOW>

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:

1. Validate CLI installation
2. Execute: fractary codex health [--category <c>] [--verbose] [--fix] --json
3. Parse JSON output
4. 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.

</WORKFLOW>

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

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

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

Permission Denied

When CLI reports permission issues:

1. Show permission error details
2. Suggest chmod/chown commands
3. Offer to fix with --fix flag

Disk Full

When CLI reports disk space critical:

1. Show severity: CRITICAL
2. Recommend immediate action
3. Suggest freeing space or expansion
4. Offer to clear expired with --fix

Corrupted Index

When CLI reports corrupted index:

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

Missing Dependencies

When CLI reports missing tools:

1. List which dependencies are missing
2. Provide installation instructions
3. Explain impact on functionality

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 checked
4. 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>

<DOCUMENTATION> 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}
───────────────────────────────────────

</DOCUMENTATION> <NOTES>

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:

1. Check CLI installation: fractary --version
2. Test CLI directly: fractary codex health
3. Check basic access: Can you read .fractary/codex/?
4. Verify dependencies: git, jq installed?
5. Check disk space: df -h </NOTES>