The cookbook

WHEN — editing any asset served with long/immutable caching

Immutable caching means an edited file is invisible to returning visitors unless its URL changes. The failure isn't forgetting to bump the version — it's bumping it incompletely, leaving some pages pointing at the year-old cached copy. So enumerate who references it, then prove exactly one version exists:

before editing a shared asset — who points at it?

git grep -l 'app.js' -- '*.html' | wc -l

after bumping — exactly ONE version string may remain

git grep -ho 'app.js?v=[0-9]*' -- '*.html' | sort | uniq -c
# more than one line of output = stop, you missed a page

Why: a machine checks version-uniqueness across the whole tree; human memory doesn't.

WHEN — you changed an inline script on a page under a strict CSP

A strict Content-Security-Policy runs an inline script only if the exact hash of its contents is allow-listed. Change one character — even whitespace — and the browser silently refuses to run it. Recompute and update the header:

hash the exact script body

echo -n 'exact script content' | openssl dgst -sha256 -binary | openssl base64
# → paste as 'sha256-…' into the script-src of your headers/CSP config

Why: the failure mode is absolute and invisible — the script just doesn't run. Better to keep executable JS in external files (allowed by 'self') and let inline blocks be data only.

WHEN — a static site was deployed by someone (or some agent) whose source you don't have

A static host serves your files but not your config — headers, CSP, redirects live in the platform, not in the served bytes. If the only copy of a deploy is the live site, you can still recover the served files and reconstruct the config from the response headers:

mirror the files, then read the config off the wire

# 1) pull the served files you can enumerate (sitemap helps)
curl -fsS https://example.com/ -o index.html
curl -fsS https://example.com/assets/app.css -o assets/app.css

# 2) reconstruct headers/CSP/cache policy from the live response
curl -sID- https://example.com/ | grep -iE 'content-security|cache-control|strict-transport|x-frame|referrer|permissions-policy'

Why: it turns an unrecoverable parallel deploy into a clean base you can build on — instead of overwriting someone's work with a stale tree.

WHEN — an agent (or you) is about to say "fixed"

"No errors in the log" is not proof anything works — it's also exactly what "the code never ran" looks like. Health needs a positive signal: drive the real flow and observe the output. Bake it into the rules so the agent does it unprompted:

context rule

# Never claim a change works from the absence of errors. Exercise the
# actual behaviour end-to-end (load the page, hit the endpoint, run the
# flow) and show the observed result before saying "done".

Why: silence is not health; the most expensive bugs are the ones that looked fine because nothing complained.

WHEN — a change matters enough that a wrong "looks good" is costly

The agent that wrote the code has the intent in its context, so it grades the work against the intent, not the artifact. Hand the verification to a fresh agent with an adversarial brief — ideally a different one from the bench:

send the diff to a second, skeptical reviewer

git diff | codex "you did NOT write this. Try to break it: find the
input that makes it wrong, or say why it's correct. Be adversarial."

Why: divergence is free review. Bugs that survive the author rarely survive a skeptic with fresh eyes.

WHEN — a task surfaced something non-obvious you'll want again

Agents start every session blank. The fix is a tiny, greppable memory: one fact per file, an index line so it's discoverable, and a bias toward the why and the never-again (the false alarms and rejected ideas are the highest-value entries).

memory/reconstruct-config-from-headers.md

---
title: Recover a static deploy's config from live headers
type: reference
---
A static host doesn't serve netlify.toml/_headers — CSP, redirects and
cache policy live in platform config. If the source is gone, reconstruct
it from `curl -sID-` response headers. See [[cache-bust-blast-radius]].

Why: the second occurrence of any problem should take minutes, not the same afternoon.

WHEN — a check or change spans more files than one context window holds

"Make sure every page does X" doesn't fit in one agent's head for a large site. Split it: one lightweight sub-agent per chunk, run in waves, aggregate only the violations. The orchestration is deterministic; the reading is parallel.

shape of a fan-out sweep

# enumerate the work, chunk it, run N sub-agents per wave,
# each returns ONLY the violations it found — then merge + de-dupe.
#   wave 1: files 1–4   → [findings]
#   wave 2: files 5–8   → [findings]
#   ...    aggregate → unique, ranked, most-severe first

Why: many small contexts beat one overloaded one — and the fast chunks don't wait on the slow ones.