cambridge-beer-festival-app

Proto-first API contract workflow for the Cambridge Beer Festival app — load before editing anything under proto/, before touching cloudflare-worker/reviews.ts or shared.ts, before acting on an automated review comment about the API design (etag/soft-delete/batch/optional/resource-parent annotations), before running any proto:* mise task, or when asked "how do I add a field to the API", "is this AIP fix correct", "what does the worker actually implement vs the proto contract", "why did buf fail to install", or "how do I regenerate the OpenAPI spec". Covers the buf/api-linter toolchain and exact command order, the AIP known-facts table for resisting wrong reviewer suggestions, existing lint suppressions and why, the CatalogService/MyFestivalService resource model, the deployed /v1alpha Review API surface and its honest gap versus the DrinkEntry proto contract, and the rules for evolving the contract without breaking it.

Load when you need the HISTORY behind a design decision, not just its current shape — before re-investigating something that "seems broken," before proposing a fix that touches state management/storage/caching/routing/connectivity/CI/proto/testing, before re-litigating an architecture choice, or when a review comment suggests reverting something or re-adding removed code (isBenignRestorationError, runtimeType matching, catalogue-decorated favourites, Patrol/Firebase E2E). Triggers — "didn't we already try this", "why is it done this way", "has this bug happened before", "why was X removed/rejected", "what did the ADR decide", "is this still open", "what's the rejected-alternatives list". Provides symptom→root-cause→evidence→status→lesson entries for every major investigation in this repo, the explicit dead-ends/rejections section, the ADR alternatives tables, and the still-open/deferred list — so nobody re-fights a settled battle.

How changes are classified, gated, and reviewed in the Cambridge Beer Festival app. Load BEFORE committing, opening a PR, merging, deciding whether a change is allowed at all, or acting on a review comment. Triggers — "can I change X", "which CI checks run", "why did PR Lint fail", "should I fix this codecov comment", "is it safe to deploy now", "do I need an ADR", "rename the favorites route", "bump a dependency", "edit festivals.json", "the reviewer says this is wrong (decision procedure for whether to act)". Provides the change-classification→CI-gate map, the non-negotiable gates with the incident behind each, the Do-Not-Modify list, four maintainer-confirmed unwritten rules (URL contract, free-tier-only, festival freeze, untouchable upstream feeds), review-comment triage, issue/ADR discipline, and a pre-merge checklist.

Load when you need to MEASURE something in the Cambridge Beer Festival app instead of eyeballing it — running `./bin/mise run test`/`analyze` and grepping the printed TEST_LOG/ANALYZE_LOG path, decoding a minified Flutter-web crash stack from a source map (how do I run the decode tooling), reading `coverage/lcov.info` or a Codecov comment, driving `scripts/check-page.mjs`/`screenshot-batch.mjs` for a headless page/console-error probe, interpreting `flutter analyze` lint/complexity output, checking what Crashlytics/Analytics actually record in production, or using `./bin/mise doctor`/`env --json`/`ls --json` to diagnose a toolchain problem. Ships two helper scripts (`scripts/decode-stack.mjs`, `scripts/lcov-summary.sh`). Does not tell you what a symptom MEANS (see `debugging-playbook`) or what makes a test good (see `validation-and-qa`).

Load when you need to understand HOW the Cambridge Beer Festival app is built rather than how to run it — before adding a screen/model/service/sort option, before touching BeerProvider or any domain controller, before adding or changing a persisted field or SharedPreferences key, before deciding where new state or logic belongs, or when a review comment claims a layer boundary was crossed. Triggers — "where does this state live", "can a controller do IO", "is this the right place for this logic", "why is _setAllDrinks the only write path", "do I need a schema migration for this field", "what's the invariant this test is protecting", "why does the provider look like this", "is AGENTS.md's architecture section still accurate". Provides the UI→Provider→controllers→repositories→services→models layer contract, the 11 enforced invariants with file:line and the incident behind each, the storage/persistence contracts (UserDataStore versioning, PreferenceKeys registry, legacy migration), load-bearing design decisions

Recreate and troubleshoot the Cambridge Beer Festival app's toolchain — mise self-bootstrap, environment layering (base/dev/human/claude-code-web), install failures, task introspection, CI-vs-local parity, and every environment-variable/config axis (MISE_ENV, dart-defines, TEST_LOG/ANALYZE_LOG, wrangler vars, BASE_URL). Load when the ask is "set up this repo from scratch", "flutter/mise install fails", "why did `./bin/mise run X` fail while installing tools", "403 / GitHub rate limit / libgit2 transport error", "what does MISE_ENV do here", "where is task X actually defined", "why does the CI build differ from my local build", "add a new mise task or tool", or "why did my Write come back reformatted". Does NOT cover running/serving/deploying the app (see `run-and-operate`) or test methodology (see `validation-and-qa`).

Load when debugging ANY misbehaviour in the Cambridge Beer Festival app — wrong/stale drinks after switching festival, one-frame flash of the previous festival, app stuck on cached data with no error, data reverting on cold start, web release "Null check operator" crashes (what does this crash symptom MEAN — the triage, not how to run the decode tooling), web build failures that work on mobile, wrong analytics environment, empty drink categories, flaky/failing widget tests (pumpAndSettle, copyWith, GoRouter, semantics, goldens), CI job failures (fmt/analyze/codecov/pr-lint/e2e/proto), or worker API errors (503 STORAGE_UNCONFIGURED, CORS rejection, 502). Provides a symptom → cause → discriminating-experiment → fix-pattern triage table for this project's real, historically-verified failure modes, plus dead-end traps not to repeat.

Maintaining the docs of record and all user/reader-facing prose in the Cambridge Beer Festival app — docs/ taxonomy and lifecycle, ADR house style and when one is required, GitHub Issue house style (title/root-cause/labels), commit and PR message format, completion-summary rules, known doc drift to fix or file, and external positioning (what's actually public, and claim discipline). Load BEFORE writing or editing anything under docs/, opening a GitHub issue, writing a commit message or PR description/title, writing an ADR, archiving a planning doc, or drafting any completion summary. Triggers — "where does this doc go", "do I need an ADR for this", "write a good issue for this bug", "what should the commit message say", "is docs/README.md up to date", "this doc looks wrong/stale", "can I say this is WCAG compliant / production-ready", "will this show up in the changelog".

Executable, decision-gated campaign for the project's hardest live problem — finishing the "My Festival" Phase 1 UI (issues #411, #413, #414, #415) AND the cloud-sync backend (D1 provisioning, v1alpha API deploy, Flutter sync client). Load when the task is "implement My Festival", "finish the tasting log", "add addTasting/removeTasting/setUserNotes", "want-to-try / tasted badge", "the My Festival screen", "multi-tasting detail screen", "provision D1 / deploy the reviews worker", "build the sync client", "wire up DrinkEntry sync", "offline outbox / flush on reconnect", or any slice of #315. Gives numbered phases with exact files, baseline + verification commands, the expected observation at each gate (and the branch to take on a surprise), the wrong paths to fence off, a ranked offline-sync solution menu, and the change-control routing (one PR per phase). NOT for unrelated bugs (see debugging-playbook) or editing the proto contract itself (see api-contract).

First-principles analysis recipes for the Cambridge Beer Festival app — "prove it, don't just install it." Load before trusting or changing API-field parsing/schema code, before building the proof/forensic method to decode a minified web-release crash, before touching any unawaited() future or shared mutable state, before acting on an automated review comment that looks wrong, before changing staleness/retry/refresh timestamp logic, or before running any experiment (test, curl, jq, coverage check) whose result you haven't predicted in advance. Triggers — "is this field really always a string", "prove this branch is dead code", "decode this crash stack (construct the forensic method)", "audit this for races", "the reviewer says X, is that true (construct the refutation)", "will this be stale after this change", "what should I expect this command to return". Provides six worked recipes, each with the exact repo incident it comes from, copy-pasteable commands, and what counts as proof (not vibes).

Domain-theory knowledge pack for the Cambridge Beer Festival app — what the festival is operationally and why that shapes the code, drink-domain vocabulary (categories, dispense, ABV, allergens, vegan, availability status), the data-feed reality (which API fields are type-unions and why), festival-registry (data/festivals.json) semantics, the API surface map (static feeds vs v1alpha Review API vs paper-only proto CatalogService), and a jargon glossary (AIP, D1, workerd, etag, keyset pagination, CalVer, etc). Load when you need to understand what a domain term MEANS in this codebase — "what is dispense", "what does status_text `arrived` mean", "why is allergens sometimes a bool", "what's the difference between v1alpha and the proto contract", "what does D1/workerd/etag/AIP mean here", "is this field stable year to year" — not when you need to run a task or edit the API contract.

The discipline that turns a hunch into an accepted result in the Cambridge Beer Festival app. Load when proposing a root cause, deciding whether a fix is "the" fix, writing an issue triage comment, drafting a planning doc, running a resilience review or data census, deciding whether an idea needs an ADR, or closing/archiving an investigation (accepted or rejected). Triggers — "is this the real root cause", "what's the fix for X", "write up this investigation", "should this be an ADR", "the reviewer suggested Y, is that right", "we tried this before, what happened", "run a census on the data", "kill this hypothesis before we ship it", "retire this planning doc". Provides: the evidence bar (explain ALL observations + survive adversarial refutation), predict-numbers-before-running, the idea lifecycle from hunch to archive, this project's preference for cheap/reversible config over flag systems, the historical sources of good ideas here, and the retirement protocol for dead ends.

Run, build, serve, and deploy the Cambridge Beer Festival app. Load when asked to start the dev server, build for web/Android, run e2e tests locally, provision Cloudflare D1, update festival data, cut a release, or figure out "where does this land / what URL is this on / which workflow deploys X". Triggers — "run the app", "build for web", "start the dev server", "serve the release build", "build an APK/AAB", "run e2e tests", "provision D1", "the database_id is a placeholder", "update festivals.json", "cut a release", "tag a release", "what does release-pr.yml do", "why didn't CI run on the release PR", "where's the staging URL", "check the worker health endpoint", "what lands in build/web". Provides the run matrix, the deployment topology table, the release-train runbook with its traps, the D1 provisioning runbook, the festival-data-update flow, output locations, and honest limits on what an agent can check operationally (no dashboard access).

Load BEFORE touching any file under lib/screens/, lib/widgets/, lib/main.dart, or lib/app_theme.dart — any visual change, new screen, restyle, "make this look nicer," redesign, new widget, colour/theme change, or accessibility fix. Triggers — "redesign the drinks screen", "add a badge to the drink card", "restyle this", "add Semantics", "make it accessible", "update the golden", "change the bottom nav", "add a route", "per-festival theme", "My Festival status badges". Provides the UI-change discipline that prevents this project's costliest historical failure mode (sweeping redesigns), a shared-widget reuse table, the WCAG 2.1 AA Semantics catalogue, the screen patterns that must never regress (festival-flash guard, four-signal loading/error UI, navigateToRoute), and My Festival's visual-design constraints.

Load before writing or judging ANY test in the Cambridge Beer Festival app, before claiming a change is "tested" or "verified," before updating golden screenshots, or when deciding what kind of test a change needs. Triggers — "write a test for X", "is this test good enough", "update the goldens", "add a semantics test", "what counts as done here", "TDD this bug fix", "does this need a widget test or a unit test", "the coverage dropped", "can I say this was manually tested". Provides the evidence hierarchy (unit/widget > goldens > worker vitest > Playwright smoke > manual — with Playwright's hard canvas-rendering limitation spelled out), the deep-vs-shallow test doctrine, verified copy-paste skeletons for every test type in this repo (model JSON, pure controller, mockito provider, GoRouter-wrapped widget, golden, semantics, worker vitest, functions vitest), the TDD red/green/refactor workflow with the `@visibleForTesting` extraction pattern, acceptance thresholds (coverage, analyzer, format), and the definitio