cambridge-beer-festival-app: Skill for Claude Code

Reference: Domain Theory for the Cambridge Beer Festival App

This is background knowledge, not a runbook. It explains what things mean so you can read code, triage a bug, or read a review comment without having to reverse-engineer intent from field names. For "how do I run/build/fix this" go to the sibling skills named throughout and in "When NOT to use" at the end.

1. The domain: what the festival actually is

The Cambridge Beer Festival is a real-ale festival organised in the tradition of CAMRA (the Campaign for Real Ale) — the app's own festival descriptions call it "the longest-running CAMRA beer festival in the UK (since 1974)" (data/festivals.json, cbf2025.description) and the Play Store listing points users to "the official Cambridge CAMRA website" for authoritative festival info (docs/tooling/play-store.md:90). This app itself is an unaffiliated community app — "not affiliated with or endorsed by the Cambridge Beer Festival organizers" (docs/tooling/play-store.md:88) — built and maintained independently of CAMRA.

Two editions exist, both modelled as Festival entries in the registry (see §4):

• Main festival (cbf{year}) — the big summer event, roughly a week long, on Jesus Green, Cambridge (data/festivals.json: cbf2026 runs 2026-05-18..05-23). Full beverage range: beer, international beer, cider, perry, mead, wine, apple juice, low/no-alcohol.
• Winter festival (cbfw{year}) — a smaller winter edition at the Corn Exchange (cbfw2025: 2025-12-10..12-13, available_beverage_types: [beer, low-no] only — a genuinely narrower catalogue, not a data gap).

Three operational facts drive real design decisions in this repo — they are not incidental:

1. Burst usage, one week a year. The app's entire yearly value is concentrated into ~6 days. There is no ops capacity during the festival (one maintainer, often on-site) — this is why the project enforces a pre-festival deploy freeze (skill change-control §5) and a free-tier-only infrastructure rule (same skill §4 Rule 2).
2. The venue has patchy, mobile-only data. Confirmed both by the maintainer and in writing: docs/planning/rating-service/design.md:18 states the offline design choice ("Optimistic local + background sync") is because "Festival venues have patchy signal." Jesus Green and the Corn Exchange are marquees/halls with no reliable venue WiFi — attendees are on mobile data, often congested (thousands of people, one cell tower). This is the design-driving constraint behind the whole SWR (stale-while-revalidate, see §6 glossary) caching architecture: render cached data instantly, refresh in the background, never block the UI on a network round-trip, keep showing stale data with a dismissible notice rather than an error screen. See skill architecture-contract for the mechanism and its historical bug family (#302, #306–#309).
3. Volunteers update availability ad hoc. status_text (see §2) is typed in free text by festival volunteers at the bar as casks run low or arrive — not from a structured inventory system. That is why the vocabulary is inconsistent, why it can change between festivals (the _statusMap carries an arrived entry — historical winter vocabulary per issue #348/#349 records, not reproduced in the current live feeds), and why the parser cannot assume an ordinal/structured field exists (§3).