docs(dev): document cache-corruption recovery, the cost of enabling the cache

Stress-tested the failure mode rather than assuming it: deliberately corrupting
an SST block makes Turbopack abort with a FATAL panic — it does not self-heal.

  FATAL: An unexpected Turbopack error occurred.
  Cache corruption detected: checksum mismatch in block 4 of 00000221.sst

`bun run dev:cache:prune` and restart fixes it; verified the canvas serves 200
again afterwards. Documented in the skill and in the script's header, since the
symptom is a hard crash and the remedy is not guessable.

This is the honest cost of turning the cache on. It is worth paying — a 5.4x
faster restart against a rare, loud, single-command failure — but it should be
written down rather than discovered.

Worth distinguishing from the adjacent case: an ordinary hard kill does *not*
corrupt the cache. Turbopack discards a partially-written cache and rebuilds it
silently, which is exactly why a `kill -9`-based benchmark reads as "no cache
win" (noted in the benchmarking section).

Author: waleedlatif1

.agents/skills/dev-performance/SKILL.md

@@ -39,6 +39,23 @@ The dev cache is unbounded on disk — an abandoned one in this repo reached **7
 
 Chained explicitly rather than via a `predev` lifecycle hook: Turbo does fire `pre*` hooks (verified), but an explicit `&&` is visible in the command, survives any invocation path, and needs no per-variant `predev:*` duplicate.
 
+### If the dev server dies with a Turbopack panic
+
+An on-disk cache can be corrupted (disk full, an OS crash, a bad write). Turbopack does **not** self-heal from that — it detects the checksum mismatch and aborts:
+
+```
+FATAL: An unexpected Turbopack error occurred.
+Cache corruption detected: checksum mismatch in block 4 of 00000221.sst
+```
+
+The fix is one command, then restart:
+
+```bash
+bun run dev:cache:prune
+```
+
+This is the known cost of the cache being on, and it is worth it: the cache buys a 5.4x faster restart, and the failure is loud and single-command rather than silent or subtle. Note that an ordinary hard kill does **not** corrupt the cache — Turbopack discards a partially-written cache and rebuilds it silently (which is why a `kill -9` benchmark reads as "no cache win").
+
 ## How to benchmark a dev-performance change
 
 Anything less than this and the number is not trustworthy.

.claude/commands/dev-performance.md

@@ -38,6 +38,23 @@ The dev cache is unbounded on disk — an abandoned one in this repo reached **7
 
 Chained explicitly rather than via a `predev` lifecycle hook: Turbo does fire `pre*` hooks (verified), but an explicit `&&` is visible in the command, survives any invocation path, and needs no per-variant `predev:*` duplicate.
 
+### If the dev server dies with a Turbopack panic
+
+An on-disk cache can be corrupted (disk full, an OS crash, a bad write). Turbopack does **not** self-heal from that — it detects the checksum mismatch and aborts:
+
+```
+FATAL: An unexpected Turbopack error occurred.
+Cache corruption detected: checksum mismatch in block 4 of 00000221.sst
+```
+
+The fix is one command, then restart:
+
+```bash
+bun run dev:cache:prune
+```
+
+This is the known cost of the cache being on, and it is worth it: the cache buys a 5.4x faster restart, and the failure is loud and single-command rather than silent or subtle. Note that an ordinary hard kill does **not** corrupt the cache — Turbopack discards a partially-written cache and rebuilds it silently (which is why a `kill -9` benchmark reads as "no cache win").
+
 ## How to benchmark a dev-performance change
 
 Anything less than this and the number is not trustworthy.

.cursor/commands/dev-performance.md

@@ -34,6 +34,23 @@ The dev cache is unbounded on disk — an abandoned one in this repo reached **7
 
 Chained explicitly rather than via a `predev` lifecycle hook: Turbo does fire `pre*` hooks (verified), but an explicit `&&` is visible in the command, survives any invocation path, and needs no per-variant `predev:*` duplicate.
 
+### If the dev server dies with a Turbopack panic
+
+An on-disk cache can be corrupted (disk full, an OS crash, a bad write). Turbopack does **not** self-heal from that — it detects the checksum mismatch and aborts:
+
+```
+FATAL: An unexpected Turbopack error occurred.
+Cache corruption detected: checksum mismatch in block 4 of 00000221.sst
+```
+
+The fix is one command, then restart:
+
+```bash
+bun run dev:cache:prune
+```
+
+This is the known cost of the cache being on, and it is worth it: the cache buys a 5.4x faster restart, and the failure is loud and single-command rather than silent or subtle. Note that an ordinary hard kill does **not** corrupt the cache — Turbopack discards a partially-written cache and rebuilds it silently (which is why a `kill -9` benchmark reads as "no cache win").
+
 ## How to benchmark a dev-performance change
 
 Anything less than this and the number is not trustworthy.

scripts/prune-turbopack-cache.ts

@@ -12,7 +12,12 @@
  * the win it exists to provide. This script drops the whole cache once it crosses a
  * threshold; Turbopack rebuilds it on the next run (one cold compile, ~32s).
  *
- * Runs automatically on `predev`. Also invokable directly:
+ * Also the remedy when Turbopack aborts with `Cache corruption detected:
+ * checksum mismatch` — it does not self-heal from a corrupted cache, so prune
+ * and restart. (An ordinary hard kill does not corrupt it; Turbopack discards a
+ * partial write and rebuilds silently.)
+ *
+ * Runs automatically before every `dev` script. Also invokable directly:
  *   bun run scripts/prune-turbopack-cache.ts            # prune if over the cap
  *   bun run scripts/prune-turbopack-cache.ts --force    # always prune
  *   bun run scripts/prune-turbopack-cache.ts --dry-run  # report only