zakariaf/Flutter-Skills

# Accessibility is a coding standard, not a checklist

Accessibility is authored into the widget as you write it — the same tier as "the button actually works." There is no lint for any of this: `flutter_lints` and `very_good_analysis` ship zero a11y rules. Enforcement is the widget itself, review of your own diff, and widget tests. Applies to every interactive View, every `Icon`/`Image`, every state, and every color choice.

Testing mechanics (guideline matchers, golden lanes, RTL, honest conformance limits) live in `widget-golden-and-a11y-testing`; this skill is the authoring discipline.

## Non-negotiable rules

1. **Every interactive node gets `Semantics(button: true, label: ...)`** — a raw `GestureDetector` with no semantics silently locks out every screen-reader and switch user. Correct semantics make TalkBack, VoiceOver, Switch Access and Switch Control work for free; it is definition-of-done, never a backlog ticket.
2. **Every `Icon`/`Image` gets a `semanticLabel`, or is wrapped in `ExcludeSemantics`** because it is decorative. There is no third option — an unlabelled `Icon` is invisible to a screen reader.
3. **Read a11y state from `MediaQuery` at build time, never from app state.** `MediaQuery` is an `InheritedWidget` with correct-by-construction invalidation; pushing it through a provider trades a compiler-guaranteed rebuild for a frame of staleness in the one area where being wrong is total failure.
4. **Never `MediaQuery.withClampedTextScaling`, never `textScaleFactor`.** Both are clamping hacks that silently defeat the text-scale matrix while contrast and tap-target guidelines still pass green. Enforce with a source grep (see Anti-patterns).
5. **Never `FittedBox`, computed `fontSize`, or `TextOverflow.ellipsis` to make a label fit.** They turn "doesn't fit at 200%" from a loud test failure into truncated or shrunk text on a device. Build flexible heights and let text wrap.
6. **Never encode state through color alone.** Pair every stateful signal with at least one non-color channel — icon + text label + shape/pattern + position. Color-only state is invisible under `invertColors`, grayscale color-correction, and to every screen-reader user.

# Adaptive Layout

Adapt to the **space you are given**, never to the device you think you are on. A phone in a foldable's front display, a resized desktop window, and a tablet in split-screen all defeat `Platform.isX` checks — but they all report their real constraints. Branch on width, not hardware.

Read the reference for the task at hand:

- `references/window-size-classes.md` — the Material 3 window size-class breakpoints as a shared vocabulary, the `WindowSizeClass` enum pattern, `MediaQuery.sizeOf`/`paddingOf`/`viewInsetsOf` vs `.of`, readable max-width, SafeArea and display cutouts, keyboard insets, orientation, foldable hinge awareness.
- `references/list-detail-and-navigation.md` — single-pane-navigate vs side-by-side two-pane, choosing the navigation affordance by width and coordinating with the go_router shell, keeping selection state in a Notifier so both panes agree.

Run `scripts/check_adaptive.sh` before a PR.

## Non-negotiable rules

1. **Adapt by constraints/size, never by device or platform.** No `Platform.isAndroid`/`Platform.isIOS`/`kIsWeb` to pick a *layout*. Use `LayoutBuilder` (local box constraints) or `MediaQuery.sizeOf(context)` (window size). WHY: a resized window, split-screen, and foldable all break device checks; constraints are always true.

# Ads and IAP monetization

The policy layer over the ads and billing seams: *what* a rewarded view grants, *when* an
interstitial may fire and how often, *how* an entitlement gates both, and *in what order* they
initialize at launch. It assumes the seam already exists — declaring the interface, overriding it per
flavor, and keeping SDK types out of feature code belong to `service-boundary-and-native`.

The model this encodes is **free, opt-in-first**: value is exchanged for attention the user chose to
give, and one non-consumable purchase removes the exchange. It is not the only viable model, but the
rules below are what keep any ad-funded app honest, reviewable, and out of the "feels like adware"
bucket.

## Non-negotiable rules

# App startup and bootstrap

`main()` has one job: install a crash net, read the little state the first frame needs, wire real dependencies into the tree, and hand off to `runApp` — fast, ordered, and unable to hide a failure. Everything expensive happens after the first frame or off the launch path entirely.

## Non-negotiable rules

1. **Error handlers go first, before anything that can throw.** A crash-log sink, `FlutterError.onError`, and `PlatformDispatcher.instance.onError` are installed immediately after `WidgetsFlutterBinding.ensureInitialized()`. The step most likely to throw is opening the DB; installing handlers after it inverts the whole point.
2. **Exactly two error handlers — no zone.** `FlutterError.onError` (build/layout/paint errors) and `PlatformDispatcher.instance.onError` (uncaught async errors) cover every path. **Never add `runZonedGuarded`.** The "you need all three" advice is crash-SDK advice (Sentry wraps its init in a zone); with no such SDK a zone buys nothing and costs a documented zone-mismatch footgun. Flutter's own fix for that warning is to remove zones.
3. **`PlatformDispatcher.onError` returns `true` unconditionally.** Returning `false` routes to the embedder fallback, where the process may exit or hang. Get debug-console visibility from `debugPrint` under `kDebugMode`, not from `return kReleaseMode`.
4. **Never let an error handler throw.** Wrap its body in a bare `try/catch (_)` and keep the comment explaining why the discarded error is deliberate — otherwise someone "fixes" it into infinite recursion inside the handler.
5. **Read settings/theme before `runApp`.** Palette, text-scale policy, locale, and any first-paint choice are read synchronously (a handful of rows is sub-10ms) so frame one paints correct. A flash of the wrong theme is a visible defect, not a cosmetic one.
6. **Construct real infra in a composition-root `bootstrap()`, inject via overrides.** Feature code depends on **throwing placeholder providers**; `bootstrap()` builds the real DB/services and `overrideWithValue`s them in the root `ProviderScope`. A forgotten wiring fails loudly at startup, never returns null. This is also the test seam.
7. **Defer warm-up to `addPostFrameCallback`; never await it in `main()`.** Any plugin/engine warm-up (audio, TTS, first network handshake) runs its cost synchronously on the main thread and produces ANRs on the cold-start path. Fire it best-effort after the first usable frame.
8. **Do not block the first frame.** The only launch-path `await` is the one unavoidable blocker (opening the DB). Show the UI shell immediately rather than a blank window while a migration runs.

# Async safety: no failure may be silent

Async bugs are silence. A dropped `Future` swallows its error; a dead `BuildContext` throws into a void; a leaked subscription fires into a disposed widget. An app with no telemetry has exactly two feedback loops — the analyzer and the test suite — and the analyzer has one hole big enough to drive the product through. Close it structurally, not with discipline. This skill applies whenever you write `async`/`await`, wire a callback, or hold a subscription, timer, or sink.

## Non-negotiable rules

1. **A callback must never touch a `Future`.** Every `onTap`/`onPressed`/`onSubmitted`/`VoidCallback` handler returns `void`. `onTap: () => vm.save(x)` where `save` is async is caught by NO lint (see below) — the fix is shape, not vigilance.
2. **A `mounted` / `ref.mounted` guard goes after EVERY await, immediately before the next `BuildContext` use** — never once at the top, never before the await where it proves nothing. Or capture the object you need before the gap.
3. **Multiple awaits ⇒ the guard sits after the LAST one.** A guard only certifies the interval since the most recent suspension point.
4. **`unawaited(x)` is legal only if `x` provably cannot fail silently** — it ends in a `.catchError(...)` or is total. Bare `unawaited(f)` routes errors to `PlatformDispatcher.onError`, detached from the UI. That is silence with a permission slip.
5. **Every `StreamSubscription`, `StreamController`, `Timer`, and sink is released** in `dispose()` / `ref.onDispose`. Prefer not owning it: a provider gives teardown for free.
6. **Every timer/stream callback that calls `setState` guards `mounted` first.** A `Timer` holds a strong reference to its closure and fires happily after the widget is gone.
7. **No empty catch, no bare catch, no swallow.** Every `catch` has an `on` clause (except the crash logger's own write), logs with its stack, and surfaces the failure. Use `rethrow`, never `throw e` — the latter resets the stack trace.
8. **Never `assert` a platform/plugin return value.** Asserts are stripped in release: green in every test, absent on the device — the perfect silent-failure bug.

# CI Pipeline & Gates

A CI gate is not a decorative green check — it converts one release-blocking contract into a check a build either passes or fails, *without trusting a human*. Keep the pipeline lean: one workflow file for most single-package apps, every job pinned, every gate traceable to a named contract, and an honest note wherever CI cannot prove the thing that actually matters.

Read the reference for the task at hand:

- `references/workflow-skeleton.md` — the copy-paste single-file `ci.yml`: pinned runner + toolchain, freshness gates, format/analyze, randomized tests, host-sqlite, coverage-strip, and the release-build job.
- `references/policy-grep-gate.md` — the grep-based invariant gate: the three-criteria bar, strip-comments-first, anchor-to-structure, accumulate-and-fail-once, write-the-reason-for-a-stranger.

Run `scripts/ci-gates.sh` and `scripts/banned-strings.sh` before a PR to reproduce the static gates locally.

## Non-negotiable rules

1. **Every gate maps to exactly one named contract — name it.** A check that serves no stated contract is not a gate: make it advisory and say so, or don't add it. Never invent a merge-blocker with nothing behind it. This keeps the pipeline auditable and stops gate-sprawl.

# Codegen and toolchain

One deterministic codegen pass is the source of truth for every generated file;
run it first, scope it tightly, and decide once whether its output lives in git.
Applies whenever a project uses `build_runner` or `gen-l10n`.

Read the reference for the task at hand:
- `references/codegen-scoping.md` — the generator inventory, `generate_for:`
  scoping tables, error-to-fix recovery map.
- `references/commit-vs-gitignore.md` — the two committed/gitignored strategies,
  their tradeoffs, and the exact CI gate each one requires.
- `references/toolchain-and-workspace.md` — SDK pinning, analyzer/coverage
  excludes, and the multi-package workspace layering (fenced, opt-in).

# Custom Canvas & Gestures

Hand-painted surfaces (`CustomPainter`/`Canvas`) own every pixel, so they look byte-identical across platforms — but only if the painter stays dumb, the coordinate math is shared, and gestures translate rather than decide. This skill is the contract for that layer: how it splits, how pixels and pointers agree, and how a screen reader hears a canvas.

Read the reference for the task at hand:
- `references/painter-and-scene.md` — the View/Painter/Scene split, the shared transform, hit-testing by geometry class, zero-allocation `paint()`, the two-path repaint pitfall.
- `references/gestures-and-semantics.md` — gesture-as-translator, arena arbitration, clamp-not-collision drags, custom-canvas Semantics, action/gesture parity.
- `references/text-and-shapes.md` — measured `TextPainter` fitting, optical centring, `RoundedSuperellipseBorder`, physical-pixel hairlines, concentric radii, painter-over-image-asset.

Run `scripts/check_painter_hygiene.sh` and `scripts/analyze.sh` before a PR.

## Non-negotiable rules

1. **A canvas surface is three collaborators — a View, a Painter, and an immutable Scene — never one god-widget.** The View watches the ViewModel, builds an immutable `Scene` value type holding *everything the painter needs and nothing more*, and hands it to `CustomPaint`. The `Painter extends CustomPainter` is dumb: no `Notifier`, no `BuildContext`, no `DateTime`, no domain rules — it draws the Scene and never decides state. A dumb painter is testable and re-skinnable.

# Dart 3 idioms and coding standards

Modern Dart 3.x, value-type-first, total functions for domain logic. A language feature earns its place when it converts a runtime silence into a **compile error**; everything else is decoration. This skill governs how each declaration is *typed, named, kept immutable, and kept total* — the error-handling architecture that rides on top of these mechanics lives in `error-handling-typed-results`.

Read the reference for the task at hand:

- `references/construct-verdict-table.md` — the feature-by-feature verdict table (sealed / enum / record / class modifiers / `extension type` / codegen packages), with the rationale for each Use / Skip.
- `references/immutability-and-equality.md` — immutable value types, `copyWith`, when to hand-write `==`/`hashCode`, and stable-identity vs value-equality.
- `references/complexity-and-honesty.md` — the length/nesting limits with their evidence, and the `late`/`!`/`dynamic` honesty-dodge bans in full.

Run `scripts/check-dart3-idioms.sh` before a PR.

## Non-negotiable rules

# Dartdoc Conventions — the public surface is a contract

Public code is read far more than it is written. A symbol with no leading `_` is a **contract** callers depend on, so it carries a `///` doc a reader understands without opening the body. Doc comments use `///` and follow *Effective Dart: Documentation*. Applies whenever you add or change a public declaration, or write an in-body `//` comment.

## Non-negotiable rules

1. **Every public declaration gets a `///` doc** — public classes, constructors, methods, getters, top-level functions, typedefs, and fields. `public_member_api_docs` is an **error** with no "obvious member" exemption: it flags *every* undocumented public member, so a missing doc fails the build. Making a symbol public "just in case" is a review reject — make it `_`-private instead so it needs no doc and no contract.
2. **`///`, never `/** */`.** Dartdoc only recognizes `///`. A JavaDoc block is silently ignored and the symbol reads as undocumented. `slash_for_doc_comments` flags it.
3. **First line is one standalone sentence ending in a period, in its own paragraph.** Tools show only this sentence in API lists, so it must stand alone; a blank `///` line separates it from the body.
4. **Method/function docs start with a verb phrase** (third person): "Returns…", "Schedules…", "Loads…", "Marks…". A boolean getter or `bool`-returning method starts with "Whether…".
5. **Never restate the name.** `/// The name.` on `String name`, `/// Returns the total.` on `total()` — banned. If a public member has nothing to add beyond its name, that is the signal to make it `_`-private (a private member needs no doc, so the tension disappears). A member that must stay public still needs a real `///` — never leave it public-and-undocumented; add meaning: **units, ranges, nullability, throws, side effects**, and the invariant the symbol enforces.
6. **Cross-link identifiers in `[brackets]`** so dartdoc resolves them: `/// Throws [StateError] if [id] is unknown; see [copyWith].` `comment_references` warns on a broken link.
7. **In-body `//` explains *why*, never *what*.** The code already says what. Narrating comments (`// loop over items`) rot out of sync and become misinformation. Comment the reason, the gotcha, or the invariant.
8. **Restate an enforced invariant at its enforcement point.** Where one line upholds a guarantee — an ordering, a clamp, a persist-before-publish, a canonical-unit conversion — a terse `//` states it so a diff that weakens it gets an unmissable flag. Same for a magic constant: cite where the number comes from.

# Data export and restore

In an app with no server, the export file is the only copy of a user's data that can
outlive the phone, and restore is the only recovery path they can invoke themselves.
Both are dangerous in opposite directions: a lossy export silently becomes someone's
backup, and a half-applied restore destroys the very database it was meant to protect.
This skill governs the *portable* artifacts; the on-device `VACUUM INTO` snapshot and
WAL rules belong to `persistence-drift`.

Depth lives in `references/formats-and-encoding.md` (CSV/JSON/PDF mechanics) and
`references/restore-and-merge-policy.md` (validation ladder, merge strategies).

## Non-negotiable rules

# Dependency hygiene

Every dependency is a permanent liability someone else may have to service. Optimise for *resolves and builds years from now*, not for *latest*. This skill governs pubspec/lock mechanics, the gate a new package must pass, and the escape hatch when a critical package rots.

Read the reference for the task at hand:
- `references/dependency-gate-and-audit.md` — the refuse/accept gate, transitive auditing, licence recording, upgrade discipline.
- `references/sdk-pin-and-lint-include.md` — recording the SDK version and the silent-lint-disable trap on any SDK bump.
- `references/vendoring-behind-an-interface.md` — vendoring a bus-factor-1 native plugin into `third_party/` without touching `lib/`.

Run `scripts/audit-deps.sh` before a PR that changes `pubspec.yaml`.

## Non-negotiable rules

1. **Caret ranges in `pubspec.yaml`, exact pins only in `pubspec.lock`.** `drift: ^2.31.0`, never `drift: 2.31.0`. The lock pins; ranges only keep resolution solvable. Exact pins in a pubspec manufacture unsolvable conflicts on the next SDK bump and buy nothing the lock is not already delivering.

# Design review workflow

One structured design/QA pass per app or feature, at the very end, on the release build — never a per-task visual critique. During the build, development speed wins and no task is blocked on aesthetics; when the last build task is done and CI is green, exactly one pass runs: a screenshot sweep + an on-device pass → graded findings → one scoped fix round → a dated sign-off that gates release.

## Non-negotiable rules

1. **Once per app/feature, at the end — never per-task.** Blocking a build task on a visual critique, or demanding review screenshots inside a task's acceptance criteria, is the failure this skill prevents. If something looks broken mid-build, file a note and keep moving; review it in the pass.
2. **Trigger = last build task done AND all CI gates + tests green.** Green gates are a *precondition*, not part of the review — this pass judges only what the eye and ear catch. Never re-litigate what CI already proves (determinism, lint, l10n key parity, layer gates).
3. **Review the release build, not a debug build.** A debug banner, debug-mode jank, or an un-overridden status bar wastes the sweep. Standardize the status bar (fixed clock, full battery) so shots differ only where the UI differs.
4. **Sweep the full matrix — every screen the app can show.** Each screen × {light, dark} × {LTR, RTL} × largest text scale × reduce-motion. Dynamic screens get shot in each meaningful state (empty, mid, full/success). One file per matrix cell, machine-sortable names, all artifacts under one review folder inside the write-set.
5. **Every accessibility-floor violation is a BLOCKER — however beautiful the screen.** Contrast, tap-target size, text-scale reflow, color-never-alone, RTL correctness, and reduce-motion safety are the shared floor. A floor miss always grades BLOCKER; aesthetics never buy it back.
6. **Grade every finding BLOCKER / FIX / NOTE.** BLOCKER = floor violation or a shipping-stopper (must fix now); FIX = clearly below bar, fixable this round; NOTE = recorded, deferred to the backlog. Consolidate into one deduped table before fixing.
7. **Exactly one fix round.** Fix BLOCKERs + FIXes as a single scoped unit, re-run gates/tests, re-shoot *only* affected cells (overwrite — the folder stays one truth), verify each finding against its new shot. Open no new critique during verification — new observations become NOTEs. A surviving BLOCKER means no sign-off and an escalation, not a second round.
8. **Do destructive on-device steps last.** Force-stop, previous-release migration, wipe/reinstall, and a deliberate crash each destroy the state before them. Ordering them last means the audio/reader/scale passes aren't redone.

# design-system-structure

A design system is code that is *incapable of holding a stray opinion*: every aesthetic value lives in one directory, and every widget reads it back through a named slot. This skill owns how tokens, themes, components, and shapes are **structured and consumed** — not which colors or radii to pick (that belongs to your design source of truth). Getting the structure right makes a reskin a `diff lib/theme/` and turns a stray `Color(0xFF…)` in feature code into a build failure instead of a style nit.

Read the reference for the task at hand:
- `references/token-tiers-and-themeextension.md` — two-tier token naming, ThemeExtension mechanics, the asserting `of()`, hand-authored `ColorScheme` vs `fromSeed`, honest `lerp`.
- `references/motion-and-reduced-motion.md` — the three animations Material mounts by default, why `NoSplash` is not enough, reduced-motion-means-zero, `pumpAndSettle` bans in tests.
- `references/typography-and-fonts.md` — bundling fonts, `LicenseRegistry`, `FontWeight` drives `wght`, silent `FontVariation` no-ops, subsetting without instancing, per-script fallback cascades.
- `references/contrast-and-redundant-encoding.md` — AA as a unit test, ≥3 grayscale-legible signals per meaning, reading a11y flags from `MediaQuery`.

Run `scripts/check_raw_values.sh` and `scripts/check_font_bundling.sh` before a PR.

## Non-negotiable rules

# Error Handling — Typed Results

Recoverable failures are typed **values** that flow through the layers and are switched on exhaustively; only genuine bugs and unrecoverable states throw, and those are caught once by a global net. Wrapped around both, never-lose-data — transactions, autosave drafts, soft-delete/Undo — is a first-class subsystem, not plumbing. Two tiers, no middle ground.

Read the reference for the task at hand:
- `references/result-failure-spine.md` — the `Result`/`Failure` source, the per-boundary taxonomy, convert-at-boundary, the global net, isolate re-wrapping, and local logging.
- `references/mechanism-selection.md` — throw vs `assert` vs `Exception` vs sealed outcome, `@useResult`, and the runZonedGuarded decision.
- `references/never-lose-data.md` — one transaction per mutation, debounced autosave drafts, optimistic soft-delete / Trash / Undo behind one filter.

Run `scripts/check-swallowed-catch.sh` and `scripts/check-softdelete-parity.sh` before a PR.

## Non-negotiable rules

1. **Model recoverable failures as values, not exceptions.** Anything that fails for a runtime reason the caller must handle — DB error, file/backup I/O, notification scheduling, an expected not-found, invalid input — returns `Result<T, F extends Failure>` (sealed `Ok`/`Err`). Throwing across a layer for an *expected* failure is a review reject.

# Flutter Architecture

Structure every Flutter app as a **layered, feature-first MVVM system, sized to the app**. You must
always answer "where does this code belong?" in one second. Based on Flutter's official *Guide to app
architecture*, with Riverpod 3.x as the one mechanism for both state and dependency injection.

Two failure modes kill an architecture: under-structure (a widget touching a database) and
over-structure (a `*UseCase` wrapping one repository call, an interface over code that already runs in
a test). This skill fights both. **Start small; add a layer only when it carries a load you can name.**

Read the reference for the task at hand:
- `references/module-and-layers.md` — the layer model, folder-vs-package continuum, the DAG, barrels, feature-folder anatomy, and the "when multi-package (workspace)" note.
- `references/right-sizing.md` — the reject-over-engineering table, "abstract only what you can't test", and how architecture scales with app size.
- `references/state-di-riverpod.md` — provider graph, keepAlive vs autoDispose, placeholder-override composition root, isolate-safe factories, `ProviderContainer` tests.

# Flutter Conventions — Index

The front door for this Flutter/Dart app. It states the cross-cutting **house rules** every task obeys, then **routes each concern to a focused skill**. For any non-trivial task: apply the rules here, then open the specialized skill for depth. This is the only skill that names every other skill in the library.

Assumes a **single-package Flutter app** by default. Monorepo / pub-workspace guidance is fenced inside the skills that own it (`project-structure-and-packages`, `codegen-and-toolchain`) — never required for a small app.

## Non-negotiable rules

1. **Feature-first, layered, downward-only.** Group by feature (a folder), then by layer: View → ViewModel → Repository → Service/data. Lower layers never import upward; the dependency graph is a strict DAG. WHY: an acyclic downward graph is the only structural guard against a big ball of mud. *(`flutter-architecture`, `project-structure-and-packages`)*
2. **Widgets are dumb.** No business logic, data access, math, or formatting in a widget — it reads state and renders. WHY: logic in `build()` is untestable and rebuilds unpredictably. *(`widget-composition`)*
3. **One ViewModel per screen, over immutable state.** A single `Notifier`/`AsyncNotifier` owns private mutable state and exposes it as an immutable value with value equality; a transition assigns a new state, never mutates in place. WHY: immutable value + single owner makes every change diffable and testable. *(`state-management-riverpod`)*
4. **Riverpod 3.x is state + DI.** Modern `Notifier`/`AsyncNotifier`/`Future`/`Stream` providers only; providers are the DI container. No `get_it`, no `package:provider`, no legacy `StateProvider`/`StateNotifierProvider`/`ChangeNotifierProvider`. WHY: one composition model, no second DI framework to reconcile. *(`state-management-riverpod`, `app-startup-and-bootstrap`)*
5. **Single write path.** A widget or ViewModel never mutates persisted state directly; every mutation is a repository method that persists first, then republishes via a stream. WHY: one durable, observable route means state is never half-written. *(`state-management-riverpod`, `persistence-drift`)*
6. **Derive, don't store; depend on abstractions.** Compute derived values on read instead of caching a second copy; program against interfaces you inject, not concretes. WHY: a duplicated source of truth drifts out of sync; injected seams keep code testable. *(`flutter-architecture`, `service-boundary-and-native`)*

# Flutter Performance

Hold a steady 60 fps (<=16 ms/frame; <=8 ms on 120 Hz) on a floor device (low-end Android / older iPhone). Performance is a property you **measure in profile mode**, not one you assert. It comes from rebuilding less, painting cheaply, and keeping both the UI thread and the raster thread free.

## Non-negotiable rules

1. **`const` everything legal.** A `const` subtree is skipped on rebuild — the framework short-circuits it by identity. Keep `prefer_const_constructors` on as an error; a non-const literal that could be const is a lint failure, not a preference.
2. **Shrink the rebuild scope to the smallest changing widget.** Never `ref.watch(provider)` for a whole state object when one field changed — watch `provider.select((s) => s.field)`. A HUD counter tick must never rebuild a heavy sibling. Rebuild scope is the single biggest lever on build-thread cost.
3. **Lazy everything long.** `ListView.builder` / `GridView.builder` / slivers for variable or unbounded content. `ListView(children: items.map(...).toList())` builds every off-screen row up front — refuse it for anything not tiny and fixed.
4. **No expensive work in `build()`.** No `jsonDecode`, sort, regex, `DateTime` math, file/network, or large allocation — `build()` may run every frame. Compute in the Notifier/ViewModel once and cache the result in immutable state.
5. **Heavy CPU off the UI isolate.** Parse large payloads, process images, crunch numbers in `compute()` or a spawned `Isolate`. Blocking the UI thread is guaranteed jank; the raster thread cannot save you.
6. **Size image decode to the display slot.** `cacheWidth`/`cacheHeight` or `ResizeImage`, correct asset resolutions, `precacheImage` for above-the-fold art. Decoding a 4000 px source into a 100 px box spikes memory and OOMs cheap phones.
7. **Prefer the cheapest widget that does the job.** `ColoredBox`/`DecoratedBox` over `Container`, `SizedBox` for spacing, `FadeTransition`/`AnimatedOpacity` over the `Opacity` widget in hot paths. Avoid `ClipPath`/`saveLayer` inside scrolling lists — they force an offscreen buffer on the raster thread.
8. **`RepaintBoundary` around costly, independently-repainting subtrees** (an animation, a chart, a live indicator) so its repaint does not re-raster its neighbours. Do not sprinkle boundaries everywhere — each is a compositor layer that costs memory.

# Forms and input

Text input is where most disposal leaks, un-localized strings, and jank enter a Flutter app. A form is a small state machine: fields hold text, a `FormState` validates them, and a ViewModel owns anything that touches the network or the clock. Keep those three responsibilities separate.

Read the reference for the task at hand:

- `references/validation-sync-and-async.md` — sync `validator` returning localized `String?`, `AutovalidateMode` choice, and the debounced-async-in-a-Notifier pattern (why async must NOT live in the sync validator).
- `references/focus-and-keyboard.md` — `FocusNode` lifecycle, traversal order, `autofocus`, `FocusTraversalGroup`, `TextInputAction`, `onFieldSubmitted`/`onEditingComplete`, `keyboardType`, `autofillHints`, `TextInputFormatter`, keyboard-avoidance.

Run `scripts/check_forms.sh` before a PR.

## Non-negotiable rules

1. **Every `TextEditingController` and `FocusNode` created in a `State` is disposed in `dispose()`.** They hold native resources and listeners; a leak survives the widget and fires callbacks against a dead tree. If the value must outlive the widget, hold it in a Notifier instead — see `state-management-riverpod`.

# i18n, RTL & Localization

One contract: **store canonical, localize at render.** Every conversion and formatting lives in
one `l10n` layer; feature widgets receive value objects and already-localized strings, never raw
formatting logic. RTL is a layout discipline, not a translation task — author with logical
geometry so it mirrors by construction. Applies to any app that ships more than one locale or any
RTL locale (Arabic, Persian, Hebrew, Sorani Kurdish, Urdu).

Read the reference for the task at hand:

- `references/arb-and-icu.md` — the ARB add/translate workflow, `l10n.yaml`, ICU plural/select, placeholder typing.
- `references/rtl-and-bidi.md` — the directional-geometry allow/ban table, icon mirroring, bidi isolation, CustomPainter pinned LTR, RTL charts.
- `references/numerals-and-calendars.md` — digit systems, separator traps, format/parse, calendar projection.
- `references/unsupported-locales.md` — shipping a locale `flutter_localizations` has no data for: the probe, the vendored delegate trio, delegate ordering, font coverage.

# Lint & Style Config

Style is not taste; it is toolchain-enforced. `dart format` owns whitespace, the
analyzer owns correctness, and a small set of **silence-producing bug classes**
are promoted to build-failing errors. This skill governs the
`analysis_options.yaml` itself and the mechanics that decide whether it actually
does anything. Applies whenever you edit that file, add or silence a lint, or
bump the SDK/ruleset.

Read the reference for the task at hand:

- `references/rule-catalog.md` — every promoted rule and its bug class, the
  deliberate downgrades, the contested `public_member_api_docs` call, and the
  complexity-limit table.

# Local Notifications Scheduler

One on-device reminder engine, owned centrally, with a narrow API. The local DB is the source of truth; the OS pending set is a disposable cache. Every scheduling change flows through one pure-then-reconcile path so the whole engine is verifiable off-device. Applies whenever you schedule, cancel, or reason about local notifications.

Read the reference for the task at hand:
- `references/notification-gateway-port.md` — the port contract, the two adapters, channels/grouping/deep-link payload rules.
- `references/scheduler-and-recurrence-rules.md` — pure `ReminderScheduler.compute` diff, recurrence/DST math, deterministic IDs, budgeting, the full test matrix.
- `references/platform-boot-exact-alarms-oem.md` — boot re-arm, exact-alarm degradation, background-isolate safety, Android manifest/Gradle, the OEM survival matrix.

Run `scripts/check-single-fln-import.sh`, `scripts/check-scheduler-purity.sh`, `scripts/check-adhoc-schedule-calls.sh`, and `scripts/check-manifest-permissions.sh` before a PR.

## Non-negotiable rules

1. **The local DB is the ONLY source of truth.** The OS pending-notification set is a disposable cache you reconcile against — never the store of record. Every reminder must be reconstructible from the DB alone after process death, reboot, Doze, or restore.

# Motion and haptics

What fires, when, exactly once, and how it degrades. Feedback is the layer users feel rather than
read — an app whose taps land, whose errors are felt, and whose success is acknowledged reads as
finished; the same app with default Material feedback reads as a prototype.

**Scope boundary.** Motion *tokens* — duration roles, curve slots, the no-raw-values gate, and
`resolveMotion` collapsing to `Duration.zero` under reduced motion — are owned by
`design-system-structure`. Painter/ticker mechanics are owned by `custom-canvas-and-gestures`.
*Which* surface a message uses — loading, empty, error, snackbar, banner, dialog, Undo, and
screen-reader announcements — is owned by `ui-states-and-feedback`. This skill owns the sensory
layer those decisions ride on: which moments exist, what each one commits to, how haptics are
mapped and fired, and what survives when the animation does not.

# Naming Conventions

Consistent, role-carrying names make code searchable and self-explaining, and the suffix on a type declares which layer it lives in — so a reviewer, a `grep`, and a banned-import gate can all read the layer off the name alone. This skill is the *how*; the normative *what* is [Effective Dart](https://dart.dev/effective-dart). Never invent a house style that contradicts the language's own.

## Non-negotiable rules

1. **Types are `UpperCamelCase`.** Classes, enums, mixins, extensions, typedefs, type parameters: `TaskScreen`, `OrderStatus`, `Predicate<T>`. Consistent shape makes types visually distinct from values.
2. **Members, variables, functions, and parameters are `lowerCamelCase`.** `dueDate`, `loadTasks()`, `itemCount`. It is the language default; deviating costs readers a double-take.
3. **Constants are `lowerCamelCase`, never `SCREAMING_CAPS`.** `const maxItemsPerPage = 50;` — not `const MAX_ITEMS = 50`. Dart dropped the C convention; the analyzer expects `constant_identifier_names`.
4. **Files, folders, libraries, and import prefixes are `lowercase_with_underscores`.** `task_detail_screen.dart`, `features/task_detail/`, `import 'package:app_core/app_core.dart';`. Cross-platform filesystems and pub demand it.
5. **File name = its primary declaration, snake_cased, one primary public type per file.** `TaskNotifier` lives in `task_notifier.dart`. No `utils.dart`/`helpers.dart`/`models.dart` grab-bags and no `utils/`/`common/`/`helpers/`/`misc/` junk-drawer folders — a reader who greps a symbol must land in the file that owns it. `core/` is the *sanctioned* pure-foundation layer (value objects, `Result`/`Failure`, the `Clock` seam, pure calculators), not a junk-drawer — see `project-structure-and-packages`, which owns the layout.
6. **Acronyms longer than two letters are cased like a word.** `Json`, `Http`, `Url`, `Api` → `JsonOrder`, `HttpClient`, `fromJson`, `imageUrl` — not `JSONOrder`, `HTTPClient`. Two-letter caps-in-English acronyms may stay caps as types (`ID`, `UI`). Mixed-case acronyms are unsearchable and inconsistent.
7. **A leading underscore means library-private — use it only when you mean private.** Never prefix a public symbol with `_` to "namespace" it; that makes it unusable from another file. Public (no `_`) is a documented contract — see `dartdoc-conventions`.
8. **No Hungarian / type-encoding in names.** Not `strName`, `iCount`, `lstItems`, `userMap`, `nameString`, `itemsList`. The type system already knows the type; write `name`, `usersById`, `items`.

# Navigation and routing

This skill owns app navigation with `go_router`. There is exactly ONE `GoRouter` for the app, defined in `lib/routing/`, and every screen is reachable by a URL. Navigation is a data structure (routes + a pure redirect), not a pile of imperative `Navigator.push` calls.

Read the reference for the task at hand:
- `references/go-router-config.md` — the single router, `context.go` vs `context.push`, path params vs `state.extra`, typed route helpers, `errorBuilder`/404.
- `references/guards-and-redirects.md` — pure `redirect` functions, the Riverpod `refreshListenable`, auth + onboarding gates, avoiding redirect loops.
- `references/shells-and-deep-links.md` — `StatefulShellRoute.indexedStack` for bottom-nav/rail shells, `CustomTransitionPage`, `PopScope`, and notification-payload → location mapping.

Run `scripts/check_routing.sh` before a PR.

## Non-negotiable rules

1. **Exactly ONE `GoRouter`, built in `lib/routing/`, wired once via `MaterialApp.router` in `app.dart`.** Multiple routers fragment history, deep links, and back-button behaviour. The router is created behind a provider so guards can watch app state.

# Persistence — Drift / SQLite

The on-device store is the single source of truth: with no server, everything must rebuild from this DB alone after
process death, reboot, or restore. Push invariants into the schema, confine Drift to one layer, make every mutation
one durable transaction, and store canonical values only. Applies to any `lib/data/` Drift table, DAO, repository,
connection setup, or backup.

Read the reference for the task at hand:
- `references/schema-and-daos.md` — audit-column mixin, STRICT/CHECK/FK invariants, canonical column types, the index + `EXPLAIN QUERY PLAN` gate, DAO↔repository split, files-on-disk-with-relative-paths for blobs.
- `references/backup-and-wal.md` — the checkpoint→vacuum→verify-by-reopen primitive, WAL rules, the backup-before-anything lesson, optional SQLCipher (key-first, assert-cipher, header-check).
- `references/persistence-without-drift.md` — the same discipline for a small app on plain JSON files (injected base dir, debounce + lifecycle flush, atomic writes, lenient decode).

Run `scripts/check-drift-confinement.sh` and `scripts/check-persistence-bans.sh` before a PR. Migrations and their tests: see `run-migration`.

# Project structure & packages

The layout is a feedback loop, not decoration: structure exists so that "what imports Flutter?", "what has no test?", and "does this feature reach into another?" are answerable by `grep` and `ls`, not by trust. Default to **one Flutter package** (the app), organised **feature-first** under `lib/features/` over a shared foundation. Reach for a second, pure-Dart package only when a body of logic earns the isolation. A `pubspec.yaml` is the audit artifact — a package cannot import what it does not declare, so the dependency list *is* the layer boundary.

This skill OWNS the physical directory tree (D1). Other skills reference it rather than drawing their own.

Read the reference for the task at hand:
- `references/single-package-layout.md` — the default one-package feature-first tree, the shared-foundation folders, placement-by-failure, the deliberately-absent list.
- `references/layering-and-dependencies.md` — the downward-only DAG, feature isolation, pubspec-as-audit, the compile-firewall insight.
- `references/workspace-and-packages.md` — when (and how) to extract a pure-Dart package: barrel-over-src, `resolution: workspace`, naming the core generically.

Run `scripts/check_structure.sh` and `scripts/check_import_boundaries.sh` before a PR. The purity check auto-detects only pure roots named `*_core`; a pure package with a plain generic name (`money`, `scheduling`) must be passed explicitly, e.g. `PURE_DIR=packages/money scripts/check_import_boundaries.sh`.

## Non-negotiable rules

# Release and store shipping

CI proves the *code*; a release proves the *artifact*. Everything here is about the
exact bundle a stranger installs — built with R8, obfuscation, tree-shaking, and
release-mode asserts stripped, signed by a key you must never lose, declaring
things about itself to a store that will pull the app if they are untrue. This
skill starts where `ci-pipeline-and-gates` ends and where `design-review-workflow`
signs off.

**Building, signing, uploading, and tagging are side-effecting and irreversible in
part** (a published build number can never be reused; an iOS build can never be
unshipped). Never run them because a task seemed to imply a release — run them only
when the developer asks for a release by name. Reading and enforcing the *config*
rules below is always in scope.

# Run codegen (build_runner)

A deterministic, low-freedom runbook: regenerate all annotation-driven code in
one pass, then analyze. Run the pinned command exactly as written — do not
modify it, add flags, or hand-edit generated files. Applies whenever a source
file carries a codegen annotation (`@freezed`, `@JsonSerializable`,
`@riverpod`, `@DriftDatabase`, a drift table) and its `*.g.dart` /
`*.freezed.dart` / `*.drift.dart` part is missing or stale.

## Non-negotiable rules

1. **Run codegen BEFORE `flutter analyze`.** A fresh clone, branch switch, or
   freshly edited annotated file has no generated part on disk. Analyzing that
   tree produces misleading "missing part file" and undefined-class errors that

# Run goldens rebaseline

Blessing a golden overwrites the only record of what the UI used to look like. It is
the one operation in the test suite that *destroys* an assertion instead of running it,
so it is a **manual, low-freedom, human-run** workflow: execute the steps in order, do
not improvise, and never run it to make a failure go away.

The two-lane golden strategy, the harness, and why goldens are the *weakest* visual
assertion belong to `widget-golden-and-a11y-testing`. This skill is only the ritual for
changing the baselines.

## Non-negotiable rules

1. **A golden failure is a question, not a chore.** Before anything is regenerated,

# Run migration (forward-only Drift schema migration)

Apply a schema change to a local Drift/SQLite database by following the exact
ordered ritual below. In an offline-first app there is no server and no re-sync
path, so the on-device DB is the single source of truth: a migration that drops
or corrupts a column permanently destroys hand-entered records that exist
nowhere else, and with no telemetry nobody ever reports it — the user just
uninstalls. This is a **manual, low-freedom, human-run** workflow. Execute the
steps in order; do not improvise, reorder, or skip.

## Non-negotiable rules

1. **Take the pre-migration snapshot FIRST — before the database is opened.**
   Do it at the composition boundary that opens `AppDatabase`, never inside

# Scaffold a feature module

Stand up one feature the **same way every time**: a folder `lib/features/<feature>/` whose
`presentation/` holds a dumb View, its 1:1 Notifier/AsyncNotifier ViewModel, leaf `widgets/`, and
scoped providers (feature-local models live in an optional `domain/`). A feature is a folder, not a
package. It reads shared repositories from `lib/data/` and shared foundation from `lib/core/`, routes
every write through them, and depends only *downward* — never sideways into another feature.
(The single-package tree is owned by `project-structure-and-packages`.)

Agnostic core (holds under any state library): the View is dumb; one ViewModel per feature owns
private mutable state and exposes intent methods that assign a new immutable value; reads derive from
the repository (the single source of truth), writes go through one repository method (the single write
path, persist-before-publish); the feature depends on abstractions and navigates by route ID. The
Riverpod-first "how" below wires that with Notifiers, scoped StreamProviders, and providers-as-DI.

# Seeded determinism and golden vectors

Some output must be a **pure function of a key**: the daily pick every user compares with their
friends, a procedurally generated layout, a shareable result someone else can verify. It has to come
out identical on every device, in every timezone, on the platform build you ship next year — with no
server to arbitrate. That is a stronger property than "the tests pass", and it needs its own
discipline plus a frozen oracle to keep it.

`testing-strategy` owns *how* you test pure logic (seeded fuzz against an independent oracle, injected
`Clock`). This skill owns what makes the output reproducible in the first place, and the committed
vector table that pins it.

**A golden *vector* is not a golden *image*.** Vectors are data fingerprints for a pure generator,
asserted by `dart test` with no widget binding; reference PNGs of rendered UI belong to

# Service boundary and native

Every platform capability — reading "now", sharing, logging an event, fetching remote flags, calling a MethodChannel — crosses the app's layers as an **injected interface**. The interface names value types only; the concrete SDK lives in exactly one class; the composition root (`main`) wires one live impl; tests wire a deterministic fake. **Abstract exactly what cannot run in a test — nothing more.** This is the seam that keeps features pure, SDKs swappable, and the whole app testable headlessly.

Read the reference for the task at hand:
- `references/service-interface.md` — typed outcomes vs bool/throw, exhaustiveness, `@useResult`, hand-written env-fakes, the arrow-callback Future-drop hole, single write path.
- `references/native-channels.md` — MethodChannel placement, the cross-language contract ownership table, versioned-file-vs-`shared_preferences` traps, native-fast-path independence, the round-trip `integration_test`.
- `references/multi-flavor.md` — line-for-line composition roots, build flavors over runtime detection, per-flavor plugin pins, the banned-dependency CI graph gate.

Run `scripts/check-service-boundaries.sh` and `scripts/check-flavor-graph.sh` before a PR.

## Non-negotiable rules

1. **Every side effect is an injected interface, never a concrete SDK at the call site.** Features, Notifiers, and repositories depend on the *interface*; the app imports the real SDK in exactly one live-impl class. WHY: one seam to swap, one place to quarantine platform quirks, zero SDK reach into pure code.

# State management (Riverpod)

State and dependency injection are one mechanism: Riverpod 3.x. Each feature has one `Notifier`/`AsyncNotifier`/`StreamNotifier` ViewModel that exposes an **immutable** state value; dumb `ConsumerWidget`s read it. Widgets hold only ephemeral UI state; every durable mutation routes through one repository (the single write path). This skill covers the state-agnostic core first, then the Riverpod "how", then a Provider/ChangeNotifier appendix for the official Flutter-guide stack.

Read the reference for the task at hand:

- `references/ownership-and-lifecycle.md` — the ownership table (which provider shape), family/autoDispose/onDispose rules, composition-root DI.
- `references/reads-and-side-effects.md` — watch vs read vs listen vs select, the stale-closure hole, `void` action methods, `ref.mounted`/`BuildContext` guards.
- `references/riverpod3-api-and-testing.md` — Riverpod 3.x API shifts (legacy moves, `overrideWithValue`, retry, `ProviderContainer.test`), what 2023 tutorials get wrong, and testing seams.

Run `scripts/ban-legacy-providers.sh` before a PR.

## Non-negotiable rules

# Testing Strategy

Tests are the only correctness instrument you control at build time: shape the suite
to the code, not to a decades-old ratio, and make each test assert behaviour a build
either passes or fails. Applies to every test under `test/` and `integration_test/`.

Read the reference for the task at hand:
- `references/test-layers.md` — per-layer harness, imports, teardown, edge tables (pure core, in-memory Drift, headless Notifier, integration).
- `references/property-and-fakes.md` — fakes-over-mocks, enum-driven fake state, seeded fuzz, independent oracles, absence-of-a-failure-class tests.
- `references/coverage-and-budget.md` — file-level floors, the coverage-lies-upward fix, the suite-time budget, and the manual-pass handoff.

Run `scripts/check_test_hygiene.sh` and `scripts/run_tests.sh` before a PR.

Golden, RTL, and a11y widget mechanics live in `widget-golden-and-a11y-testing`; this

# UI states and feedback

Most of a screen's code is the happy path; most of its defects are not. This skill
governs everything a screen shows when there is no data yet, no data at all, no data
matching the filter, a failure, or a write that just returned — and which *surface* each
of those is allowed to use. The first-frame/cold-start path belongs to
`app-startup-and-bootstrap`; the error *values* belong to `error-handling-typed-results`.
This skill is only about how they are rendered and announced.

## Non-negotiable rules

1. **One state, resolved in one place.** A screen renders exactly one of
   loading / empty / error / content, chosen by a single `switch` over an `AsyncValue`
   or a sealed view state. Never a triple of `isLoading`, `error`, `items` booleans.

# Value objects: money & units

Store every quantity **once, in one canonical form, and convert only when shown or
exported**. Money is integer minor units plus a currency; physical quantities are
whole SI base units; time is UTC. This is what lets a user flip any display
preference (currency symbol, unit system, locale) without corrupting one stored
row, and lets "sum of parts == whole" be structural, not hoped-for.

This core is **pure Dart** — no `flutter/*`, no `intl`, no `dart:io`, no plugins.
Formatting and digit normalization happen upstream/downstream, not here. These
value objects live in `lib/core/`, the sanctioned pure-foundation layer (see
`project-structure-and-packages`) — never a `utils/`/`common/`/`shared/` grab-bag.

Read the reference for the task at hand:

# Widget Composition

Build every screen from many small, `const`, single-purpose widget **classes**. A widget that does one thing rebuilds cheaply, reads clearly, tests in isolation, and can be lifted into a shared component library. The View is *dumb*: it watches one ViewModel and renders; logic lives in the Notifier, state in immutable value objects, layout in directional structural primitives. Applies to any screen, list, card, or shared component.

Read the reference for the task at hand:
- `references/rebuild-mechanics.md` — why a class beats a method (`Element.updateChild`), `const` canonicalization, the full key policy, and `.select` for narrowed rebuilds.
- `references/structural-layout.md` — edge-to-edge background vs `SafeArea` content, computed cell sizing, the `GridView` cross/main-axis trap, directional insets, and IME/`resizeToAvoidBottomInset`.
- `references/widget-and-data-selection.md` — cheapest-widget table, data-class decision table (drift row vs record vs hand-written vs freezed), and gesture→fallback rules.

Run `scripts/check-widget-composition.sh` before a PR.

## Non-negotiable rules

1. **Extract a `Widget` class, never a `Widget`-returning method.** `Widget _buildHeader()` is *not* a widget — its subtree has no `Element` of its own, so `Element.updateChild` never gets to compare old vs. new and short-circuit; it rebuilds with the parent, cannot be `const`, cannot take a `Key`, and `find.byType` cannot reach it in a test.

# Widget, golden and accessibility testing

One harness pins the surface; layout and accessibility are asserted by **computed
geometry on the real widget tree**, not by blessed pixels. Goldens are a narrow,
honest safety net for glyph shaping and mirroring — never the layout gate. This
skill covers the widget tier; for the pure-core / Drift / Notifier tiers see
`testing-strategy`.

Read the reference for the task at hand:
- `references/harness-and-mediaquery.md` — pumpApp, Device presets, the four load-bearing lines, driving MediaQuery flags, finder policy.
- `references/overflow-and-textscale.md` — the two overflow classes, the three traps, the matrix, the fit assertion, and the four wrong fixes.
- `references/a11y-guidelines-and-limits.md` — the four built-in guidelines and their defects, the semantics/traversal gate, pure-Dart contrast, and what automation genuinely cannot cover.
- `references/golden-two-lanes.md` — the golden-refusal argument, the Ahem-vs-real-font lanes, RTL goldens, and blocking accidental blessing.