caching-strategy

<objective> The caching-strategy skill eliminates redundant work by intelligently caching expensive operations across workflow phases, reducing execution time by 20-40%.

Repeated work wastes time and resources:

• Reading docs/project/api-strategy.md 5 times in /plan phase (5× file I/O)
• Searching codebase for "user" pattern 3 times (3× grep execution)
• Fetching npm package info for same package repeatedly (3× network calls)
• Counting tokens in spec.md every phase (5× token calculation)
• Web searching "React hooks best practices" multiple times (3× API calls)

This skill implements smart caching with:

1. File read cache: Cache file contents until file modified (mtime check)
2. Search result cache: Cache grep/glob results for 30 minutes
3. Network request cache: Cache npm/web API calls for 15-60 minutes
4. Computed value cache: Cache expensive calculations until inputs change
5. Automatic invalidation: TTL expiration + file modification detection

The result: 20-40% faster workflow execution with zero behavior changes (transparent caching). </objective>

<quick_start> <cacheable_operations> High-value caching targets (biggest time savings):

1. Project documentation reads (15min TTL):

   • docs/project/api-strategy.md
   • docs/project/system-architecture.md
   • docs/project/tech-stack.md
   • Read once per phase, not 5× per phase

2. Codebase searches (30min TTL):

   • Grep: "user" in **/*.ts → Cache results
   • Glob: **/components/**/*.tsx → Cache file list
   • Repeated in anti-duplication, implementation, review

3. Package registry queries (60min TTL):

   • npm info for package versions
   • Dependency metadata
   • Rarely changes during single workflow

4. Web searches (15min TTL):

   • Documentation lookups
   • Error message searches
   • Best practice research

5. Token counts (until file modified):

   • spec.md token count
   • plan.md token count
   • Recompute only when file changes </cacheable_operations>

<basic_workflow> Before caching:

Phase 1 (/plan):
  - Read api-strategy.md (250ms)
  - Read tech-stack.md (200ms)
  - Read api-strategy.md again (250ms) ← Redundant
  - Grep "user" in codebase (3s)
Total: 3.7s

After caching:

Phase 1 (/plan):
  - Read api-strategy.md (250ms) → Cache
  - Read tech-stack.md (200ms) → Cache
  - Read api-strategy.md (from cache: 5ms) ← Cached!
  - Grep "user" (3s) → Cache
Total: 3.45s saved 250ms (6.7%)

Across multiple phases:

/plan:   Read api-strategy.md (250ms) → Cache
/tasks:  Read api-strategy.md (from cache: 5ms) ← Saved 245ms
/impl:   Read api-strategy.md (from cache: 5ms) ← Saved 245ms
/opt:    Read api-strategy.md (from cache: 5ms) ← Saved 245ms

Total saved: 735ms on single file across 4 phases

</basic_workflow>

<immediate_value> Typical /feature workflow (7 phases):

Without caching:

Phase reads:
- api-strategy.md: 7 reads × 250ms = 1.75s
- tech-stack.md: 5 reads × 200ms = 1s
- spec.md: 10 reads × 150ms = 1.5s
- Grep "user": 3 searches × 3s = 9s
- npm info react: 2 calls × 500ms = 1s
Total redundant work: 14.25s

With caching:

Phase reads:
- api-strategy.md: 1 read (250ms) + 6 cache hits (30ms) = 280ms
- tech-stack.md: 1 read (200ms) + 4 cache hits (20ms) = 220ms
- spec.md: 1 read (150ms) + 9 cache hits (45ms) = 195ms
- Grep "user": 1 search (3s) + 2 cache hits (10ms) = 3.01s
- npm info react: 1 call (500ms) + 1 cache hit (5ms) = 505ms
Total with caching: 4.21s

Time saved: 14.25s - 4.21s = 10.04s (70% reduction)

Savings scale with workflow length:

• Single phase: 5-10% faster
• Full /feature (7 phases): 20-30% faster
• /epic (20+ phases): 30-40% faster </immediate_value> </quick_start>

<workflow> <step number="1"> **Detect cacheable operation**

Identify operations that are:

• Idempotent: Same input → Same output
• Expensive: Takes >100ms
• Repeated: Called 2+ times
• Predictable: Output doesn't change rapidly

Cacheable:

• File reads (same file, unchanged content)
• Codebase searches (same pattern, unchanged code)
• API calls (package info, docs, rarely changes)
• Expensive computations (token counts, parsing)

Not cacheable:

• User input (unpredictable)
• Current time/date (changes constantly)
• Random values
• System state (memory, CPU)
• Database queries (data changes frequently) </step>

<step number="2"> **Generate cache key**

Create unique key for each cacheable operation:

File reads:

Cache key: `file:${absolutePath}`
Example: "file:/project/docs/api-strategy.md"

Grep searches:

Cache key: `grep:${pattern}:${path}:${options}`
Example: "grep:user:**/*.ts:case-insensitive"

Glob patterns:

Cache key: `glob:${pattern}:${cwd}`
Example: "glob:**/components/**/*.tsx:/project"

npm queries:

Cache key: `npm:${operation}:${package}`
Example: "npm:info:react"

Web searches:

Cache key: `web:${query}:${engine}`
Example: "web:React hooks best practices:google"

Token counts:

Cache key: `tokens:${filePath}:${mtime}`
Example: "tokens:/project/spec.md:1704067200"

See references/cache-key-strategies.md for comprehensive patterns. </step>

<step number="3"> **Check cache before executing**

Before expensive operation:

function readFile(path: string): string {
  const cacheKey = `file:${path}`;

  // Check cache
  const cached = cache.get(cacheKey);
  if (cached && !isExpired(cached) && !isFileModified(path, cached.mtime)) {
    logger.debug('Cache HIT', { key: cacheKey });
    return cached.value;
  }

  // Cache MISS - execute operation
  logger.debug('Cache MISS', { key: cacheKey });
  const content = fs.readFileSync(path, 'utf-8');
  const mtime = fs.statSync(path).mtimeMs;

  // Store in cache
  cache.set(cacheKey, {
    value: content,
    mtime: mtime,
    cachedAt: Date.now(),
    ttl: 15 * 60 * 1000  // 15 minutes
  });

  return content;
}

Cache check logic:

1. Generate cache key
2. Look up in cache
3. If found AND not expired AND input unchanged → Return cached value
4. If not found OR expired OR input changed → Execute operation, cache result </step>

<step number="4"> **Set appropriate TTL**

Different operations have different freshness requirements:

Immutable (cache indefinitely):

• npm package versions (once published, never changes)
• Historical git commits
• Published documentation versions

Stable (60min TTL):

• npm package metadata (latest version)
• Project documentation (rarely changes during workflow)
• Codebase structure (files/directories)

Dynamic (15min TTL):

• Web search results
• API documentation (may update)
• Error message searches

File-based (cache until modified):

• File reads → Check mtime
• Token counts → Recompute if file changed
• Parsed AST → Recompute if source changed

Session-based (cache for entire workflow):

• User preferences
• Environment variables
• Project configuration

TTL guidelines:

• Too short: Cache miss overhead negates benefits
• Too long: Stale data causes incorrect results
• Sweet spot: Long enough to avoid repeated work, short enough to stay fresh </step>

<step number="5"> **Invalidate on changes**

Automatically invalidate cache when inputs change:

File modification:

function isCacheValid(cacheEntry, filePath) {
  const currentMtime = fs.statSync(filePath).mtimeMs;
  return cacheEntry.mtime === currentMtime;
}

// Before returning cached file content
if (!isCacheValid(cached, filePath)) {
  // File modified - invalidate cache
  cache.delete(cacheKey);
  // Re-read file
}

TTL expiration:

function isExpired(cacheEntry) {
  const age = Date.now() - cacheEntry.cachedAt;
  return age > cacheEntry.ttl;
}

Manual invalidation:

// When user saves file
onFileSave((filePath) => {
  cache.invalidatePattern(`file:${filePath}*`);
  cache.invalidatePattern(`grep:*`);  // File change may affect search results
});

// When switching git branch
onBranchChange(() => {
  cache.clear();  // Full invalidation
});

Dependency invalidation:

// If spec.md changes, invalidate token count
onFileChange('spec.md', () => {
  cache.delete('tokens:spec.md');
});

</step> <step number="6"> **Monitor cache effectiveness**

Track metrics to optimize caching strategy:

Hit rate:

Hit rate = Cache hits / (Cache hits + Cache misses)

Good: >60% hit rate
Great: >80% hit rate
Excellent: >90% hit rate

Time savings:

Time saved = Σ(Cache hit time - Original operation time)

Example:
- 10 file reads from cache (50ms) vs disk (250ms)
- Saved: 10 × (250ms - 50ms) = 2000ms (2 seconds)

Cache size:

Monitor memory usage
- Target: <50MB cache size
- Evict oldest entries if exceeds limit (LRU eviction)

Metrics to log:

{
  cacheHits: 145,
  cacheMisses: 23,
  hitRate: 0.863,  // 86.3%
  timeSaved: 12450,  // 12.45 seconds
  cacheSize: 34.2,  // MB
  topKeys: [
    { key: 'file:api-strategy.md', hits: 24 },
    { key: 'grep:user:**/*.ts', hits: 12 }
  ]
}

See references/cache-monitoring.md for dashboard setup. </step> </workflow>

<cache_types> <file_read_cache> When to use: Reading same file multiple times in workflow

Implementation:

const fileCache = new Map();

function readFileCached(path: string): string {
  const cacheKey = `file:${path}`;
  const stat = fs.statSync(path);
  const currentMtime = stat.mtimeMs;

  const cached = fileCache.get(cacheKey);
  if (cached && cached.mtime === currentMtime) {
    return cached.content;  // Cache HIT
  }

  // Cache MISS
  const content = fs.readFileSync(path, 'utf-8');
  fileCache.set(cacheKey, {
    content,
    mtime: currentMtime,
    size: stat.size
  });

  return content;
}

Use cases:

• Project docs (api-strategy.md, tech-stack.md)
• Spec files (spec.md, plan.md, tasks.md

---

Content truncated.