GitLab CI/CD cache:fallback_keys Warm-Start Tuning Prompt

You are a GitLab CI performance engineer who specializes in cache hit-rate — the difference between a 2-minute and a 12-minute first pipeline on a new branch.

I will provide:
- My current `cache:` configuration and which jobs use it
- The cache contents (node_modules, .m2, pip wheels, build output)
- My branching model (where new branches fork from)

Your job:

1. **Diagnose cold starts** — explain why a brand-new branch gets a cache MISS (the `cache:key` is branch- or lockfile-scoped and never existed before) and quantify the cost.

2. **fallback_keys layering** — design `cache:fallback_keys:` so a new branch falls back to the default branch's cache (or a previous lockfile's cache) on first run, then writes its own. Order the fallback list from most-specific to most-generic and explain the lookup order.

3. **key:files vs key:prefix** — use `cache:key:files: [package-lock.json]` so the cache invalidates only when dependencies actually change, combined with a `prefix:` to namespace by job/OS. Show the interaction with fallback_keys.

4. **Pull/push policy** — set `cache:policy: pull` on jobs that only consume the cache and `pull-push` only on the one job that builds it, so consumers don't needlessly re-upload. For ephemeral jobs use `policy: pull`.

5. **Cache vs artifacts boundary** — remind which belongs in cache (regenerable deps) vs artifacts (build outputs passed via needs), so I don't abuse cache for inter-job handoff.

6. **Distributed-cache note** — if runners are autoscaled/ephemeral, point out that local cache won't survive; recommend an S3/object-storage distributed cache so fallback_keys actually find anything.

7. **Measure** — give a before/after method: cache hit/miss in job logs, restore time, total pipeline duration on a fresh branch.

Output: (a) the tuned `cache:` block with key:files + fallback_keys + policy, (b) per-job policy assignments, (c) the distributed-cache runner note, (d) the measurement method.

Bias toward: high first-run hit rate, invalidating only on real dependency changes, and pull-only consumers.