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

Proof and Analysis Toolkit

Doctrine: a claim about this codebase is not true because it sounds plausible, because a doc says so, or because a past PR title implies it — it is true because you counted, decoded, or modeled it yourself and the numbers came out the way your model predicted. Every recipe below ends in a number, a matched frame, or a written prediction that either held or didn't — never in "should be fine."

Six recipes. Each has: when to use, steps, a worked example from this repo's real history (issue/PR numbers you can hand to gh issue view or grep the CHANGELOG for), and what counts as proof.

Recipe 1 — Empirical data census

When to use: before writing or trusting any fromJson branch, before believing a claim like "field X is always a string," before changing a status/enum mapping, or before filing a bug that assumes one festival's data shape applies to all festivals.

Why it matters here: the live feeds at data.cambeerfestival.app are described in AGENTS.md as having type-union fields (abv, allergens, year_founded, bar) — but a union described in prose can silently be wrong, incomplete, or stale. The only way to know what a field actually does is to fetch every festival/category combination and count.

Steps

1. List the categories to check: beer, cider, perry, mead, wine, international-beer, low-no, apple-juice (see lib/models/beverage_categories.dart), scoped to whichever festival(s) matter — check available_beverage_types in data/festivals.json first, since per-festival unions differ (a winter festival may omit categories a summer one has, or use different vocabulary in free-text fields).
2. Fetch each {festivalId}/{category}.json — the shape is {"producers": [...], "timestamp": ...}, NOT a bare array (verify this before assuming the top-level type; see lib/services/beer_api_service.dart:110-127, parseProducers).
3. Run a jq group_by(type) census over every field you're about to parse or change.
4. Compare across at least two festivals from different seasons before concluding a union is "always X" — a summer-only sample under-counts winter-only vocabulary (or vice versa).
5. State the conclusion as a fraction, never a vibe: "branch X fires in N/M records" or "never fires in N/M records — candidate dead code" or "genuinely mixed — keep the branch."