acostanzo/refresh

Claudit: Refresh Knowledge Cache

You are the claudit cache refresh orchestrator. When the user runs /claudit:refresh, force-refresh the knowledge cache from official Anthropic documentation.

Step 1: Parse Arguments

Parse $ARGUMENTS to determine which domains to refresh:

• core-config → refresh only core configuration knowledge
• ecosystem → refresh only ecosystem knowledge
• optimization → refresh only optimization knowledge
• all, empty, or missing → refresh all three domains (default)

Step 2: Prepare Cache Directory

Run via Bash: mkdir -p ~/.cache/claudit

Step 3: Get Current Version

Run via Bash: claude --version 2>/dev/null → store as CURRENT_VERSION

Tell the user:

Refreshing knowledge cache (Claude Code v{CURRENT_VERSION})...

Step 4: Dispatch Research Agents

Dispatch the selected research agent(s) in parallel using the Task tool. All must be foreground (do NOT use run_in_background).

Research Core (if domain is core-config or all):

• description: "Research core config docs"
• subagent_type: "claudit:research-core"
• prompt: "Build expert knowledge on Claude Code core configuration. Read the baseline from ${CLAUDE_PLUGIN_ROOT}/skills/claudit/references/known-settings.md first, then fetch official Anthropic documentation for settings, permissions, CLAUDE.md, and memory. Return structured expert knowledge."

Research Ecosystem (if domain is ecosystem or all):

• description: "Research ecosystem docs"
• subagent_type: "claudit:research-ecosystem"
• prompt: "Build expert knowledge on Claude Code ecosystem features. Fetch official Anthropic documentation for MCP servers, hooks, skills, sub-agents, and plugins. Return structured expert knowledge."

Research Optimization (if domain is optimization or all):

• description: "Research optimization docs"
• subagent_type: "claudit:research-optimization"
• prompt: "Build expert knowledge on Claude Code performance and over-engineering patterns. Fetch official Anthropic documentation for model configuration, CLI reference, and best practices. Search for context optimization and over-engineering anti-patterns. Return structured expert knowledge."

Step 5: Write Cache

For each domain that was refreshed:

1. Write the agent's results to the corresponding cache file using the Write tool:

   • ~/.cache/claudit/core-config.md
   • ~/.cache/claudit/ecosystem.md
   • ~/.cache/claudit/optimization.md

2. Read the existing ~/.cache/claudit/manifest.json (if it exists) to preserve timestamps for domains that were NOT refreshed.

3. Write ~/.cache/claudit/manifest.json. For partial refreshes, only update the refreshed domains' cached_at and preserve the rest. Only update the top-level claude_code_version and cached_at when ALL domains are refreshed (either explicitly via all or because all three were specified):

   {
     "claude_code_version": "{CURRENT_VERSION if all domains refreshed, otherwise preserve existing}",
     "cached_at": "{current timestamp if all domains refreshed, otherwise preserve existing}",
     "max_ttl_days": 7,
     "domains": {
       "core-config": { "cached_at": "{current if refreshed, preserved if not}" },
       "ecosystem": { "cached_at": "{current if refreshed, preserved if not}" },
       "optimization": { "cached_at": "{current if refreshed, preserved if not}" }
     }
   }
   

Why: Consumers check per-domain cached_at for TTL and the top-level claude_code_version for version invalidation. Updating these on partial refreshes would incorrectly mark non-refreshed domains as fresh. See ${CLAUDE_PLUGIN_ROOT}/references/cache-check-protocol.md for the full cache contract.

Step 6: Report

Display a summary:

╔══════════════════════════════════════════════════╗
║         CLAUDIT CACHE REFRESHED                  ║
╠══════════════════════════════════════════════════╣

Claude Code: v{CURRENT_VERSION}
Refreshed:   {list of domains refreshed}
Cached at:   {timestamp}
Expires:     {timestamp + 7 days}

Cache: ~/.cache/claudit/
╚══════════════════════════════════════════════════╝

Other tools that benefit from this cache:
  /claudit        — skips research phase on next audit
  any agent task  — building a skill, configuring an MCP, authoring
                    CLAUDE.md, etc. — can pull current Claude Code
                    knowledge from the cache instead of re-fetching
                    docs.