caching-strategy

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

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

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)