Read first section is canonical..dart/pubspec.yaml/build.yaml/analysis_options.yaml write batch, emit Pre-Flight; its cited rule/reference owns the applicable check.Read only the narrowest matching Trigger Map row(s); scenario/subsystem rows own incidental stack/file words. Do not bulk-read references/ or parent refs. Cite exact refs in Pre-Flight.
| ID | \nRule | \nDetail refs | \n
|---|---|---|
| R1 | \nFlutter/Riverpod package = first wire flutter_skill_lints + riverpod_lint, then run package-root dart analyze + its project-owned Dart Decimate check; pure-Dart CLI = native Dart analysis profile with neither plugin. | \nanalysis-options.md, dart-decimate.md, setup.md | \n
| R2 | \nEvery provider uses @riverpod / @Riverpod codegen; no manual provider classes or legacy provider families. | \nriverpod-codegen.md | \n
| R3 | \nGuard async gaps with ref.mounted / context.mounted; finally uses if (ref.mounted) { ... }. | \nasync-mutations.md | \n
| R4 | \nWidgets are public classes; no _buildXxx(), widget top-level helpers, or private widget classes except State. | \natomic-design.md, performance.md | \n
| R5 | \nNullability is semantic; no empty/null/bool sentinel fallbacks, value!, nullable collections, or raw required domain strings. | \nvalue-objects.md, freezed-sealed.md; Lints: domain_raw_required_string | \n
| R6 | \nAll user-facing strings, tooltips, semantics, and visible accessibility copy use AppLocalizations. | \nlocalization.md, accessibility.md | \n
| R7 | \nImmutable state/entities use sealed Freezed, one declaration per file, native switch, and VO map/when disabled. | \nfreezed-sealed.md, value-objects.md | \n
| R8 | \npresentation/widgets/ renders immutable inputs + emits typed callbacks; screens/routes/notifiers own navigation, workflow, domain state, and infrastructure. | \npresentation-widgets.md | \n
| R9 | \nDuplicate behavior in 2+ classes becomes a small stateless *Mixin with an on clause. | \nmixins.md | \n
| R10 | \nStorage SDK calls live in local datasources behind repositories; production Hive imports use hive_ce_flutter. | \nhive-persistence.md, architecture.md | \n
| R11 | \nPrimitive/context/collection operations live in core/extensions/; domain never imports those extensions. | \ncontext-ui.md, primitive-formatting.md, collections-helpers.md | \n
| R12 | \nDomain primitives with meaning become validated Freezed Value Objects; Hive models keep primitives and mappers bridge. | \nvalue-objects.md, hive-persistence.md; Lints: domain_unit_primitive | \n
| R13 | \nTyped GoRouter routes are navigation SSOT; redirects are pure resolver logic with nullable by-id fallback UI. | \ndeep-linking.md, routing-app-shell.md | \n
| R14 | \nDialogs/sheets render immutable snapshots, pop results, and leave mutations/teardown to notifiers. | \nmodals-navigation.md, state-management-lifecycle.md | \n
| R15 | \nDebounce, gate, and batch high-frequency UI, sync, persistence, remote-function, reset, and lookup boundaries. | \ndebounce-gate-batch.md | \n
| R16 | \nApp shell stays declarative; bootstrap listeners live in a sibling root ConsumerWidget. | \nrouting-app-shell.md | \n
| R17 | \nKeep control flow flat after exits; remove unnecessary else after return / throw / break / continue. | \nLint: avoid_unnecessary_else_after_control_flow | \n
| R18 | \nUse onReorderItem post-removal indexes directly; never add legacy onReorder adapter math. | \nLint: use_on_reorder_item_index_semantics | \n
| R19 | \nAndroid exact alarms use flutter_local_notifications permission APIs, not manual settings intents. | \nLint: use_local_notifications_exact_alarm_permission_api | \n
| R20 | \nResolve nullable platform-specific plugin implementations before calling platform members. | \nLint: resolve_platform_specific_implementation_before_use | \n
| R21 | \nWidget previews are preview-only with deterministic fakes; no real HTTP/Firebase/Hive/native plugins. | \nwidget-previews.md | \n
| R22 | \nRuntime E2E proves behavior with stable selectors, failure-sensitive scenarios/logs, subject-matched evidence, source-of-truth verification, cleanup, and multi-actor proof when needed. | \ndart-mcp-e2e-testing.md | \n
| R23 | \nAccessibility is UI correctness: localized tooltips/semantic labels, 48x48 targets, contrast, text scale, Text.rich. | \naccessibility.md, flutter-optimizations.md | \n
| R24 | \nIf remote error reporting is accepted or already present, use one app-owned Crash boundary and one reporting owner per operation; otherwise add no provider/facade. Scrub sensitive data + reconcile ambiguous remote outcomes before telemetry. | \nerror-reporting.md, networking.md | \n
| R25 | \nWindows installer delivery = one semantic engine + typed app config/capabilities + minimal-step exact-SHA diagnostic → one publisher; keep cheap guards before one build, isolate synthetic preservation proof, and activate only verified immutable bytes. | \nwindows-installer-pipeline.md, workflow scaffold, inno_bundle pubspec scaffold, Inno settlement sentinel, Defender scanner | \n
| R26 | \nPause-sensitive Riverpod state starts only after its durable owner/listener exists; projections watch base state directly; switching auth/form modes clears transient errors. | \nnotifier-structure.md, state-management-lifecycle.md, testing.md | \n
| R27 | \nNative/custom links use one URI contract across producer, platform registration, Flutter delivery, and typed router; prove cold/warm + signed-state delivery on the target device. | \ndeep-linking.md, dart-mcp-e2e-testing.md | \n
Before writing code in any row below, read the listed reference(s). Prefer the narrowest matching row. Read the large parent refs only when no scenario row fits.
\n| Touching | \nRead | \n
|---|---|
New app/project scaffolding with incidental stack/package mentions, main.dart, ProviderScope, MaterialApp.router, app startup shell | \nsetup.md + architecture.md + routing-app-shell.md | \n
Notifier/AsyncNotifier shape, sync Notifier.build() init, paused route/listener startup, provider projection, auth/form mode error reset, loading/progress, AsyncValue, cleanup | \nnotifier-structure.md + state-management-lifecycle.md + testing.md | \n
Mutation method, ref.read / ref.watch / ref.listen, _ensureRepository, async cancellation, ref.mounted, optimistic update, duplicate fetch | \nasync-mutations.md + state-management-lifecycle.md | \n
Freezed entity, sealed union, fromJson / toJson, copyWith, model vs entity, build.yaml for explicit_to_json | \nfreezed-sealed.md | \n
Provider declaration, @riverpod, family, keepAlive, codegen, Mutation<T> (experimental) | \nriverpod-codegen.md | \n
Repository, datasource, domain entity, layered architecture, IHttpService, mapping models to entities | \narchitecture.md | \n
Value Object, primitive obsession, Distance/Money/Email/Slug, unit conversion in domain, cross-entity primitive, double distanceMeters/int amountCents/String email smell, arch_domain_import error | \nvalue-objects.md | \n
GoRouter, typed route, redirect, auth-protected route, router provider, context.go, deep link, custom URI scheme, native extension/activity link, cold-start, navigation gate | \nrouting-app-shell.md + deep-linking.md | \n
| HTTP, network, REST, source-of-truth fetch after mutation, long-running remote function, async-start + reconcile, transport id vs domain id | \nnetworking.md + debounce-gate-batch.md | \n
Atom, molecule, organism, design tokens, atomic widgets, core/widgets/ promotion | \natomic-design.md | \n
Reusable presentation/widgets/, widget-owned navigation/page stack/selected entity/workflow state, direct repository/service/provider access | \npresentation-widgets.md | \n
| Accessibility, semantics, tooltip, semanticLabel, image alt text, tap target, contrast, text scaling | \naccessibility.md + flutter-optimizations.md | \n
Widget test, ProviderContainer.test(), UncontrolledProviderScope, fakes, mocks, AppWidgetKeys, event-contract tests | \ntesting.md | \n
flutter_driver, Dart MCP, Marionette MCP, E2E, integration_test, semantic selectors, scenario validation, screenshot/media proof, log capture, native integration builds but fails on device, runtime permissions, plugin hangs, release-only runtime failure | \ndart-mcp-e2e-testing.md | \n
Hive, TypeAdapter, TypeId, box, persistence migration, retired field accounting | \nhive-persistence.md | \n
Crashlytics, FirebaseCrashlytics, Sentry, sentry_flutter, DSN, error reporting, Crash.init, Crash.error, Crash.log, symbol upload | \nerror-reporting.md | \n
| Mixin, capability vs interface, retry helper, RNG, bulk operation | \nmixins.md | \n
Service, singleton, fire-and-forget, abstract final class, unawaited(), Future<void> signature | \nservices-and-singletons.md | \n
@Preview, widget_previews.dart, preview fakes, deterministic preview data | \nwidget-previews.md | \n
AppLocalizations, ARB file, gen-l10n, locale fallback, placeholders, plural / select | \nlocalization.md | \n
Performance, build cost, .select(), const constructors, ListView.builder, large list compute | \nperformance.md + flutter-optimizations.md | \n
LayoutBuilder, RenderFlex overflow, Expanded / Flexible outside Row / Column, Positioned outside Stack, text-scale clamp | \nlayout-diagnostics.md | \n
| Pagination, infinite scroll, cursor loading, search debounce, registration/form validation and submission, batch processing, pull-to-refresh | \nlists-forms-workflows.md + async-mutations.md | \n
BuildContext helpers, ModalRoute current-route checks, dialogs, SnackBarUtils, snackbar dispatch from notifier | \ncontext-ui.md | \n
DateTime format/diff/timeAgo/startOfDay, String capitalize/truncate/titleCase/initials/format, int / double / num clamp/pluralized/asCurrency/percent/toFixed, Duration format, NumberFormat, DateFormat, intl | \nprimitive-formatting.md | \n
Iterable lookup/indexing, widget list helpers, Debouncer, validators, Result, extension types, core/extensions/ barrel export | \ncollections-helpers.md | \n
Records (x, y), extension type IDs, pattern matching, primary/concise constructors, new(), factory(), dot shorthand such as .center, @RecordUse | \ndart-patterns-records.md | \n
Flutter/Riverpod analysis_options.yaml, dart analyze, plugin wiring, riverpod_lint version pin, analyzer crash | \nanalysis-options.md + analysis_options.yaml | \n
| Skill setup, Git pre-push, hook/scanner registration | \nsetup.md | \n
build_runner, missing generated parts, clean checkout, Xcode selection, Flutter SwiftPM generated package, Apple device build, local-vs-CI mismatch | \nbuild-reproducibility.md + core-stack.md | \n
| Package constraints, dependency upgrade, generator/analyzer compatibility | \ncore-stack.md | \n
Flutter Windows desktop packaging, GitHub Actions Windows installer, Inno Setup, inno_bundle, updater/auto-update, CRT DLLs, PowerShell/native installer process, installer/version/AppId failure | \nwindows-installer-pipeline.md + build-reproducibility.md + core-stack.md | \n
| Dart Decimate, dead code, circular dependency, duplicate code, complexity, dependency hygiene, full zero-finding scan | \ndart-decimate.md | \n
| Common navigation / form / list / debounce / route-param-fallback patterns | \ncommon-patterns.md | \n
| Incremental remote pull, delta token, per-table sync date, merge/delete reconciliation | \ndelta-sync.md | \n
| Route-param safety, wizard sequencing, guarded next-step navigation | \nnavigation-flow.md | \n
| Dialog / sheet / modal, snapshot value object, post-await teardown, dismiss-then-route, pop fallback, nested navigator dismissal | \nmodals-navigation.md + state-management-lifecycle.md | \n
Debounce / throttle / coalesce — TextField.onChanged, Slider.onChanged, scroll listener, sync saveAll, full-collection rewrite after subset mutation, persistence helper, reset/clear sentinel preservation, _userTapped gate, WebView / VideoPlayer in build, _storage.read in service, ref.listenManual ban, keepAlive collection watch, datasource batch loader, zero-value save guard, primitive→VO at notifier boundary, routeSettings on modal helper | \ndebounce-gate-batch.md | \n
After each .dart / pubspec.yaml / build.yaml / analysis_options.yaml write batch, emit a checked list before yielding. Fill T0 always. Add T1 for state/notifier/mutation changes and T2 for network/E2E/stream/route changes. Cite rule IDs or refs for any failed item.
dart analyze exits 0 with flutter_skill_lints + riverpod_lint; setup changes prove one diagnostic from each plugin. Pure-Dart CLI: native Dart analysis profile applies; both plugins are N/A.python3 .hooks/hard-eng.py check; another project uses its established check or, if it has none, pnpm dlx --config.ignore-scripts=false --allow-build=dart-decimate dart-decimate@latest check . --threshold 0 --format json from its Git root. The project workflow schedules an integrated run; reuse its valid result instead of duplicating a full runner. Cite scan scope. Do not add a wrapper, dependency, or global coordinator for this skill.ref.mounted / context.mounted, no bare mounted, and finally uses if (ref.mounted) { ... }.Notifier.build() avoids pre-return state reads; async primary state uses AsyncNotifier.build; durable sync startup does not depend on microtask timing before its owner/listener exists.ref.onDispose() cancels subscriptions/controllers/timers; durable status/snackbar/teardown belongs to notifier state.ref.watch inside notifier methods.AppWidgetKeys; no inline string keys or coordinate primary taps.main.dart; unknown scenarios fail; critical logs fail the run; evidence shows the asserted screen before app exit; cleanup is verified.