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".