new-relo: Instructions file for Claude Code

crosbynews.com — Cloudflare Worker

Working with this repo

• This is a live, complete, self-maintaining production site. Make targeted changes only — don't rebuild it.
• After deploying, verify against the live site with curl (deploys land in ~10–40s) — check the headers/routes you touched. Sample more than once: a new Worker version reaches Cloudflare's edges over a minute or two, so a single curl can return the OLD page from a colo that has not rolled over yet (CLAUDE_NOTES.md has the full propagation gotcha + sampling script).
• Keep this file current: when you change a route, a behavior, or an invariant that lives outside the Worker, update CLAUDE.md in the same PR.
• Where state lives, by kind: docs/pages/<page>.md (one file per content page — handler, content, data source, canonical URL, sitemap presence, meta, CSP) and docs/endpoints/ (same, for non-page routes) — a PR that changes any of that MUST update the matching file in the same PR. docs/ops/<topic>.md is the same rule for cross-cutting operational config that isn't a page or endpoint (CI, GitHub settings, domain/DNS, MCP registry, email auth, news pipeline). All three record current expected state, not history — overwrite them, don't append. Dated write-ups go in docs/audit/ or docs/investigations/ instead, and are never edited in place. CLAUDE_NOTES.md (repo root) is a current-state catch-all for anything that doesn't fit those categories. docs/README.md explains the full split.

Agent operating notes (process, not site mechanics)

Not about the Worker's behavior — about working this repo session-to-session as a coding agent. A human reading for site behavior can skip this section. Narrower tooling trivia (exact gh install steps, curl/JSON gotchas) lives in CLAUDE_NOTES.md, not here — this keeps only the rules that apply regardless of tooling specifics.

• TaskList/TaskCreate do NOT persist across sessions. The persistent backlog is GitHub Issues — queryable/writable via mcp__github__* (list_issues, issue_write, …). Prefer filing backlog items as Issues (labeled backlog) over encoding them into a trigger prompt or CLAUDE.md.
• Verify a new external upstream before writing any feature code against it. A sandbox/container curl succeeding is not sufficient proof — Google News answers fine from a container but 503s the deployed Worker's IPs (why the news pipeline runs out-of-band; see docs/ops/news-pipeline.md). Pattern used for NHC/EPA/Open-Meteo: add a temporary /debug-<name>-canary route, npx wrangler deploy it for real (not wrangler dev — must be the actual edge runtime + egress IPs), curl the live URL for a real 200 + body, then git restore and redeploy clean before building on it.
• A check that reuses the code under test cannot falsify it. A 2026-08-05 audit wrongly concluded HHD had stopped publishing pollen counts because it probed for "missing" days by GENERATING candidate URLs from the same date pattern the parser uses — inheriting the exact bug it existed to find. When checking whether a parser is missing data, extract what the upstream actually serves with a deliberately looser pattern and diff against our parse — never re-derive the expected input from our own logic.
• AskUserQuestion can fail silently in automated/routine-driven sessions (no human available to answer synchronously). When genuinely blocked on a decision only the user can make, don't retry the tool — lay out the tradeoffs in your response text and end the turn.
• A backgrounded command's trailing cleanup fires against a file it has never seen. Mutation-checking a test by editing a source file and restoring it in a trailing cp /tmp/x.bak src/... is safe only while the command runs to completion in the foreground. On 2026-08-25 one such check hung on a deliberately pathological ReDoS input, the harness moved it to the background, and it fired its restore minutes later over a file that had since gained two merged PRs' worth of work — reverting 163 lines of src/features/tropics.js into an unrelated commit and to production. git status was clean because the overwrite landed before git add -A, so nothing looked wrong; the diff stat was the only tell. Restore from git, not a /tmp copy (git checkout -- <file>), and read git show --stat HEAD before pushing a commit that touched several files.
• .claude/skills/*/SKILL.md files drift independently of CLAUDE.md — nothing forces them to be touched when a feature ships (/kv's SKILL.md once went two feature-cycles describing three keys after a fourth shipped). When a change touches something a skill describes, grep the skills directory too, not just this file.