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](references/cache-key-strategies.md) for comprehensive patterns.
</step>

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

Before expensive operation:

```typescript
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 c