omar-hanafy

Use when adding, renaming, or removing a screen, route, tab, popup, redirect, or deep link in a Flutter app that uses the router_builder package - the one with @RT annotations, RouteInfo, RouteArgs, RoutePolicy, and a generated routes.g.dart with Routes/RoutesHelper classes.

Use when a deep link in a router_builder Flutter app opens the wrong screen or nothing at all, RoutesHelper.resolveDeepLink or DeepLinkMatcher.match returns null, custom-scheme links (myapp://...) behave differently from https links, allowedHosts seem ignored, deepLinkMap keys do not resolve, or the build fails with deep-link key conflicts.

Use when router_builder code generation misbehaves - routes.g.dart missing, stale, or not updating, build_runner failing with RouterBuilderError (deep-link key conflicts, @RTConfig errors, branch enum mismatch), @RT routes not discovered, dependency solve failures around analyzer/build/source_gen/dart_style when adding or upgrading router_builder, or customizing builder options (output path, class names, fail_on_conflict).

Use when a router_builder route behaves unexpectedly at runtime - auth gates firing on public screens or not firing on private ones, routes stacking duplicates or refusing to open twice, dialogs/sheets not treated as popups, navigation landing inside the wrong navigator or replacing the whole stack, redirect routes looping, nav bar visibility wrong, or RoutesHelper category lists (authorizedRoutes, globalRoutes, popupRoutes) not matching expectations.

Use when executing a confirmed router_builder 2.x to 3.x upgrade, or when code shows v2 tells - flat RouteInfo/RouteArgs params like isGlobalOnly/isIdSlug/mustBeAuthorized as constructor args, imports of package:router_builder/models/..., MyRoutes/RouteInfoHelper, a generated route_info_helper.dart, or RouterBuilderConfig.setDefaults with named parameters. For a version bump where the path is still unclear, start with upgrade-router-builder.

Use when proactively auditing a Flutter app's router_builder route definitions while nothing is failing yet - before a release, after adding many routes, when asked to "check our routes/deep links/auth gating", or when hunting for misconfigured RoutePolicy, latent deep-link key conflicts, or auth gaps across @RT declarations.

Use when integrating the router_builder package into a Flutter app for the first time, wiring its RouteInfo/RouteArgs/RoutesHelper output into GoRouter or Navigator, setting app-wide route defaults (@RTConfig or RouterBuilderConfig), or restructuring how an app organizes its @RT route declarations.

Use when a project wants to update the router_builder package to a newer version and the migration path is unclear - "upgrade router_builder", "move to the latest router_builder", dependency bumps from 1.x or 2.x, or deciding whether an upgrade is breaking before touching code.

Use when reviewing code in an app that depends on bug_handler - PR review, "check our error handling", pre-release audits, or "are we using bug_handler correctly". Finds violations of the guard contract: string errors in state, unreported catches, raw exceptions crossing repository boundaries, missing source labels, misused isReportable.

Use when bug_handler reports are missing, duplicated, delayed, or unexpected - "nothing arrives in Sentry", "capture doesn't send", "errors only show sometimes", outbox files piling up in bug_report_outbox, StateError about initialization, or events arriving that should have been suppressed.

Use when connecting bug_handler to a delivery backend or enriching its reports - writing a custom Reporter (Sentry, Crashlytics, Slack, first-party HTTP endpoint), a custom ContextProvider (feature/session/cart context), or an EventTransform. Also use when someone tries to use the shipped Sentry/Crashlytics "adapters" (they are empty placeholder files).

Use when writing or refactoring feature code in an app that depends on bug_handler - repositories/services that can fail, cubits/blocs/notifiers/controllers that load data, error states, try/catch blocks, or "handle errors properly" requests. Also use when choosing which exception type to throw or how errors should reach the UI.

Use when a project depends on bug_handler 0.0.1-dev.x or contains its legacy API - BugReporter, ErrorHandler, handleError, wrapper, ReportResult, ReportConfig, sentryDsn, ManualReporter, SentryReporter, ErrorDisplayWidget, or imports like package:bug_handler/core/error_handler.dart - and needs to move to the current 1.0.0-dev.x API.

Use when adding the bug_handler package to a Flutter app for the first time, wiring BugReportClient/ClientConfig/BugReportBindings at bootstrap, choosing providers, sanitizers, Policy, or reporters, or when initialization questions come up (init order, runZonedGuarded, flush on startup, per-environment config).

Use when configuring or debugging bug_handler sanitizers and filters - masking PII/secrets in reports, DenyListFilter/AllowListFilter paths, payload size limits, fields arriving masked that should be readable, fields arriving readable that should be masked, or compliance requirements on diagnostic data.

Configure or troubleshoot Language Server Protocol support in a flutter_monaco 3.x application using WebSocket, desktop stdio bridge, or custom transport. Use for connectLanguageServer, transport selection, CSP, stable document URIs, reconnect policy, and LSP lifecycle. Do not use for general editor integration or unrelated completion providers.

Diagnose unknown or cross-layer failures where flutter_monaco is on the failing path, including boot, assets, Web mounting, protocol, Monaco focus, overlays, page reload, LSP, or scroll handoff. Use when the package's failing layer is not yet established or a MonacoException crosses boundaries. Route an already-localized LSP transport, CSP, URI, or lifecycle problem to configure-flutter-monaco-lsp. Do not use for routine integration or a standard Flutter TextField or form issue that does not render or import flutter_monaco.

Integrate flutter_monaco 3.x into a Flutter application, including editor lifecycle, documents, platform setup, focus, overlays, and disposal. Use when adding MonacoEditor or MonacoController, designing an editor screen, or reviewing a new flutter_monaco integration. Do not use for a 2.x migration, LSP-only work, package bridge maintenance, or a bundled Monaco engine upgrade.

Change or review flutter_monaco's internal Dart-to-JavaScript bridge, command/event envelopes, generated page, platform WebView adapters, or typed public wrappers. Use inside the flutter_monaco package when adding a command, event, capability, bridge module, or protocol behavior. Do not use for ordinary consuming-app integration or arbitrary JavaScript escape-hatch code.

Migrate an application from flutter_monaco 2.x to 3.x using the complete API and lifecycle map, or migrate 1.7.1 after its toolchain and Windows prerequisites are verified. Use when pubspec or source still uses legacy content methods, model APIs, full-state options, old focus/events, old readiness, or page configuration. Do not use when the app is already fully on 3.x or when upgrading the bundled Monaco engine inside this package.

Upgrade the Monaco Editor engine and bundled assets inside the flutter_monaco package while preserving bridge, LSP, worker, cache, warmup, and archive invariants. Use when changing MonacoAssets.monacoVersion or replacing assets/monaco/min. Do not use for upgrading the Dart package dependency in a consuming app.

Use when replacing the visibility_detector package with scroll_spy in a Flutter app, when migrating VisibilityDetector, VisibilityInfo, or VisibilityDetectorController code, or when a VisibilityDetector-based feed additionally needs a single stable primary item, per-item focus metrics, or scroll-performance improvements.

Use when scroll_spy misbehaves in a Flutter app and the cause is unknown: primaryId stays null, focusedIds stays empty, listeners or builders never fire, focus ignores jumpTo or programmatic scrolls, the highlighted item is offset under a pinned header or app bar, state resets on setState, nested scrollables interfere, or a widget test reads null focus state.

Use when adding the scroll_spy Flutter package to a screen or feature: autoplay video feeds, current-item tracking, reading-position or TOC highlighting, impression analytics, carousels or PageViews, photo grids, prefetching around the focused item, or wiring ScrollSpyScope, ScrollSpyItem, and ScrollSpyController for the first time, including widget tests for that integration. Not for scrolling work unrelated to focus or visibility tracking (saving/restoring scroll offsets, scroll physics, scroll-to-index).

Use when upgrading a Flutter project from scroll_spy 0.1.x or 0.2.x to 1.x, when a build breaks after a scroll_spy upgrade with unresolved names such as ScrollSpyRegistry, ScrollSpyGeometry, ScrollSpySelection, ScrollSpyDiff, or commitFrame, or when estimating how much work the 0.x to 1.x upgrade needs.

Use when a Flutter screen whose code uses scroll_spy (ScrollSpyScope, ScrollSpyItem, ScrollSpyController) shows jank, dropped frames, high CPU, or rebuild storms, or when choosing between ScrollSpyItem, ScrollSpyItemLite, focus builders, listeners, and snapshot listening in large scroll_spy feeds. Not for general Flutter list or image scrolling performance where scroll_spy is not involved.

Use when scroll_spy selects the right things but behaves badly over time: the primary item flickers or alternates between two items, switches too eagerly or too sluggishly, stutters at card boundaries in autoplay, goes null between items or during fast scrolls, sticks to an old item too long, or updates at the wrong moments (mid-drag versus after settling).

Use when adding a new conversion target type or changing any conversion method signature in THIS convert_object repository - new toX/tryToX pair, new optional parameter, changed defaults - anything that must stay consistent across the Convert facade, top-level functions, Converter fluent API, Map extensions, and Iterable extensions.

Use when changing app-wide or scoped parsing behavior of the convert_object Dart package - ConvertConfig, default locales or number/date formats, custom truthy/falsy boolean tokens (BoolOptions), URI scheme policies (UriOptions), registering custom types with TypeRegistry so Convert.toType<T> handles them, scoped overrides via runScopedConfig/ConvertConfig.overrides, or wiring the onException hook for logging/telemetry (Sentry, Crashlytics).

Use when a convert_object conversion in Dart fails or returns surprising values - ConversionException thrown, dates off by timezone or wrong month/decade, Unix epoch seconds vs milliseconds confusion, toBool silently returning false, unexpected null from tryToX/tryGetX, strings coerced into mailto/tel URIs, list/set element conversion errors, alternativeKeys not picking the expected key, or when reading ConversionException context and fullReport output.

Use when a Dart/Flutter project uses dart_helper_utils (DHU) conversion APIs and should move to the convert_object package - ConvertObject.toX/tryToX calls, ConvertObject.toString1, ParsingException, bare top-level toNum/toInt/toDateTime helpers, firstValueForKeys, makeEncodable/safelyEncodedJson, DHU <= 5.x map/iterable getX/tryGetX conversions - or when upgrading dart_helper_utils to v6+, which delegates all conversion to convert_object.

Use when writing or reviewing Dart/Flutter code that turns dynamic or untyped data (JSON payloads, Map<String, dynamic>, lists, query params) into typed values with the convert_object package - fromJson factories and model layers, map getInt/getString/tryGetX getters, Convert.toX/tryToX calls, .convert fluent chains, List/Set/Map element conversion, enum parsing, alternativeKeys fallbacks, or nested key/index navigation.

Use when bumping the convert_object Dart package version in a project or auditing an upgrade's impact - moving from a 1.0.0-dev beta to stable 1.x, from 1.0.x to 1.1.x, reviewing behavior changes like the alternativeKeys first-non-null fallback, tryGetRaw availability, runScopedConfig override semantics, ConversionException stack traces/toString changes, or answering "is it safe to upgrade convert_object".

Use when upgrading a Flutter project from flutter_helper_utils 8.x (or 7.x) to 9.x, or when code hits removed v8 APIs after a version bump - notifier utilities gone, addOpacity/addAlpha undefined, pReplacement/pNamed undefined, dataWhen undefined, core.dart/colors.dart/widgets.dart imports failing, or dart_helper_utils v6 conflicts.

Use when building responsive/adaptive Flutter layouts or list UIs with the flutter_helper_utils package - PlatformTypeProvider setup, Breakpoint detection (watchBreakpoint/readBreakpoint, mobile/tablet/desktop), BreakpointLayoutBuilder, TypedListView/TypedSliverList, buildListView on iterables, pull-to-refresh, infinite scroll (onEndReached), item spacing/separators, empty states, or scrollCacheExtent tuning.

Use when Flutter code parses, converts, or manipulates colors with the flutter_helper_utils package - string-to-Color parsing (hex/rgb/hsl/hwb/named CSS), opacity and channel changes (setOpacity, setAlpha), darken/lighten/shade/tint, WCAG contrast and accessibility checks, color-blindness simulation, color harmonies, toHex output, or reading Colors from JSON/Map config (toColor, tryGetColor).

Use when bumping the flutter_helper_utils package version in a project or auditing an upgrade's impact - detecting the installed version, sequencing migration hops across v7/v8/v8.5/v9, patch-level 9.x bumps, or answering "is it safe to upgrade flutter_helper_utils".

Use when writing or reviewing Flutter code that uses the flutter_helper_utils package - BuildContext theme/text/colorScheme getters, MediaQuery shortcuts (sizePx, widthPx, textScaler), navigation helpers (pushPage, popPage, forcePopPage, dismissAllPopups, routeArgs), platform detection (PlatformEnv, isMobileWeb), AsyncSnapshot.when pattern matching, focus/scaffold-messenger/directionality helpers, num/Size sugar, or deciding between the main import and sugar.dart.

Use when adding the biometric_vault Flutter package to an app or wiring a feature on top of it - storing tokens, passwords, or keys behind Face ID / Touch ID / fingerprint / device-credential authentication, building an app-lock gate, choosing StorageFileInitOptions, or setting the package up for Android, iOS, macOS, Linux, Windows, or web. Not for debugging an existing integration that fails at runtime (use troubleshoot-biometric-vault) and not for converting an app from the biometric_storage package (use migrate-from-biometric-storage).

Use when a Flutter app that currently uses the biometric_storage package (by authpass / Herbert Poul) should switch to biometric_vault - replacing the dependency, converting BiometricStorage/BiometricStorageFile/IosPromptInfo code, or when stored secrets from biometric_storage must survive the switch. Also applies when biometric_vault reads return null after such a switch. Not for fresh integrations without biometric_storage history (use integrate-biometric-vault).

Use when writing or fixing Dart/Flutter tests for app code that uses the biometric_vault package - unit or widget tests that must run without a device or emulator, tests simulating authentication failures (user cancellation, lockout, storage invalidation), or tests failing with MissingPluginException on the biometric_vault channel. Not for testing the plugin's own native implementations.

Use when an app using the biometric_vault Flutter package misbehaves at runtime - AuthException codes such as failedToStart or lockedOut, StorageInvalidatedException after users change biometric enrollment, SecurityError -34018 on macOS, reads returning null unexpectedly, prompts not appearing or appearing twice, silent-writes stores where writes succeed while reads keep failing, or biometric flows that behave differently on the iOS simulator than on real devices. Not for first-time package setup (use integrate-biometric-vault) and not for converting an app from biometric_storage (use migrate-from-biometric-storage).

Runtime verification recipe for biometric_vault - build, launch, and drive the plugin end to end on the iOS simulator with controllable biometry state.

Use when Dart/Flutter code needs debouncing, throttling, stream shaping, or bounded-concurrency async work with the dart_helper_utils package - search-input debounce, rate-limited event streams, Debouncer/DebouncedCallback/Throttler lifecycle and disposal, TimeUtils.debounce/throttle/runWithTimeout, stream bufferCount/window/rateLimit/asPausable/withLatestValue/retry/replaceOnError, StreamController safeAdd/safeClose, Future minWait/timeoutOrNull, retry with exponential backoff, waitConcurrency, or mapConcurrent.

Use when upgrading a project from dart_helper_utils 5.x or earlier to 6.x, or fixing compile errors after that bump - ConvertObject/toString1/ParsingException renames, altKeys to alternativeKeys, firstValueForKeys to tryGetRaw, removed Paginator/DoublyLinkedList/country data/StringSimilarity, httpFormat to httpDateFormat, flatJson to flatMap, TimeUtils.throttle signature change, percentile 0-100 range, delay methods, or helpers that moved to convert_object or package collection.

Use when bumping the dart_helper_utils package version in a project or auditing an upgrade's impact - detecting the installed version, sequencing migration hops across v2/v3/v4/v5/v6, patch-level 6.0.x bumps, or answering "is it safe to upgrade dart_helper_utils".

Use when writing or reviewing Dart/Flutter code that uses the dart_helper_utils package - deep map utilities (flatMap, unflatten, getPath, setPath, deepMerge), string casing/slugify/masking/parseDuration/truncate, MIME filename checks, iterable chunks/windowed/partition/distinctBy, number stats and HTTP status helpers, DateTime and Duration extensions, intl formatting wrappers (formatAsReadableNumber, dateFormat, pluralize), Uri rebuild, or deciding between dart_helper_utils and direct collection/intl/convert_object imports.

Use when marker_widget markers are slow, cause jank, use too much memory, re-render repeatedly, or show stale icons after theme, locale, selection, or account changes - covers MarkerCacheKey design, clearCache and removeFromCache invalidation, maxCacheEntries and maxCacheBytes tuning, render deduplication, MarkerIconRenderer.shared, and render-once preloading.

Use when asked to review, audit, or sanity-check how a Flutter codebase uses the marker_widget package - hot-path renders without cache keys, incomplete or non-value-equal cache keys, undeclared image dependencies, missing advanced-marker prerequisites, unbounded caches, oversized renders, or marker-test hangs. Produces a read-only findings report; not for fixing code, general Flutter reviews, or projects that do not depend on marker_widget.

Use when marker_widget output is wrong or failing - blank or transparent marker bitmaps, network images missing inside markers, MarkerImageLoadException, MarkerRenderException from a broken marker widget, markers sized wrong or blurry, advanced markers or PinConfig pins not appearing, StateError or ArgumentError from MapBitmapOptions or rendering, "No FlutterView is available", or widget tests that hang or time out on marker rendering. Stale icons after theme, locale, or state changes are a cache-key concern - use marker-widget's optimizing skill for those.

Use when adding widget-rendered markers, advanced marker pins, or ground overlays to Google Maps in a Flutter app with the marker_widget package - choosing among toMarker, toAdvancedMarker, toAdvancedPinMarker, toBitmapDescriptor, toMarkerIcon, and toGroundOverlayBitmap, sizing output with MarkerRenderOptions and MapBitmapOptions, declaring imageDependencies, or wiring advanced markers (mapId, markerType, web marker library).

Use when cached_video_thumbnail misbehaves - ThumbnailException errors (timeout, network, unsupportedMedia, extractionFailed), thumbnails failing instantly on retry, wrong or stale images, cache misses or repeated extraction, scroll jank blamed on thumbnails, black or rotated frames, HLS streams, or Android/iOS behavior differences.

Use when adding video thumbnails to a Flutter feed, grid, list, chat, or gallery with the cached_video_thumbnail package, when choosing ThumbnailSpec sizes, priorities, prefetch, or engine configuration, or when reviewing an existing integration for scroll jank and performance problems.

Use when replacing the video_thumbnail, flutter_video_thumbnail_plus, get_thumbnail_video, or fc_native_video_thumbnail package with cached_video_thumbnail, or when code still calls VideoThumbnail.thumbnailData, VideoThumbnail.thumbnailFile, or FcNativeVideoThumbnail and should move to the cached engine.

Use when writing or fixing unit/widget tests for Flutter code that uses cached_video_thumbnail - tests that must run hermetically under flutter test without native plugins, platform channels, or network, or that hit MissingPluginException / path_provider errors from ThumbnailEngine or VideoThumbnailImage.