cache-refresh

Files (1)

• SKILL.md

SKILL.md (first lines)

# Cache Refresh Skill

## Purpose
Keep all skill caches fresh by detecting when source files change and triggering targeted cache updates. Prevents stale data from causing wrong file paths, missing registrations, or outdated function line numbers.

## Activation
- **Incremental**: After Claude creates, deletes, or renames a file during a task
- **Full refresh**: When user says "refresh caches" or when caches are older than 7 days

Note: skills do not run at session start. The session-start hook surfaces cache ages;
this skill defines what to do when the user or another skill asks for a refresh
(for example, after the hook reports stale caches).

---

## How It Works

This skill does NOT use a file watcher daemon. Instead, it hooks into Claude's own actions — every time Claude creates or modifies a file, this skill updates the relevant caches incrementally.

---

## Phase 1: Track File Changes During Session

After Claude creates, renames, or deletes a source file, determine which caches are affected:

```
File change → Affected caches:

New .cs file (Entity)       → file-index, backend-patterns (Function Index), post-creation-verify
New .cs file (Controller)   → file-index, architecture-scanner (apiRoutes), backend-patterns
New .cs file (Service)      → file-index, backend-patterns
New .tsx/.ts file            → file-index, frontend-patterns (Function Index)
New .service.ts file         → file-index, architecture-scanner (apiRoutes)
New .hook.ts file            → file-index, frontend-patterns
New route added              → architecture-scanner, file-index
DI registration changed      → post-creation-verify (registration points may shift)
DbContext changed             → post-creation-verify (registration points may shift)
Any file deleted              → file-index (remove entry), pattern cache Function Index (remove entry)
```

---

## Phase 2: Incremental Update Rules

### After creating a new feature:
```
1. Add new files to file-index/index.md under the correct feature section
2. Add new API routes to architecture-scanner/cache.json apiRoutes
3. Add new function entries to pattern cache Function Index sections
4. Update post-creation-verify registration points if DI/DbContext files were modified
5. Update session-resume recentFiles.modified list
6. Update task-journal with completed task
```

### After modifying an existing file:
```
1. If function was added/removed → update Function Index entries
2. If DI file was modified → update post-creation-verify registration points
3. If route was added → update architecture-scanner apiRoutes
```

### After deleting a file:
```
1. Remove from file-index
2. Remove from architecture-scanner apiRoutes (if controller/service)
3. Remove function entries from the pattern cache Function Index
```

---

## Phase 3: Staleness Detection

When a refresh is requested (or the session-start hook has flagged old caches), check what is actually stale:

```
1. Read each cache's "generated" date
2. If older than 7 days → mark for full refresh
3. If git is available: run `git log --since="CACHE_DATE" --name-only --pretty=format:""`
   → Get list of files changed since cache was generated
   → If changed files overlap with cached paths → mark for targeted refresh
4. If no git: compare cache date only
```

### Staleness levels:
```
Fresh (< 1 day old, no conflicting changes): Use as-is
Stale (1-7 days, minor changes): Incremental update
Expired (> 7 days): Full rescan
```

---

## Phase 4: Full Refresh

When triggered by user ("refresh caches") or expiry:

```
1. Regenerate file-index/index.md (scan all features)
2. Regenerate architecture-scanner/cache.json (scan routes)
3. Regenerate backend-patterns function-index (scan key files)
4. Regenerate frontend-patterns function-index (scan key files)
5. Regenerate post-creation-verify/cache.json (rescan DI line numbers)
6. Regenerate build-check/cache.json (rescan build commands)
7. Update all "generated" dates
```

Run these as parallel agents for speed.

---

## Phase 5: Integration

```
After every file creation/modification by Claude:
  1. cache-refresh determines which caches are affected
  2. Updates them incrementally (add/remove entries)
  3. No full rescan needed for single-file changes

When the session-start hook reports cache ages:

From TheophilusChinomona/idev, MIT.

More from TheophilusChinomona/idev