mindsystem-cc 3.21.0 → 3.22.1

package/skills/flutter-senior-review/principles/dependencies-data-not-callbacks.md

@@ -1,75 +0,0 @@
----
-title: Reduce Coupling Through Data
-category: dependencies
-impact: MEDIUM-HIGH
-impactDescription: Stabilizes widget APIs
-tags: coupling, parameters, typed-objects, widget-api
----
-
-## Reduce Coupling Through Data, Not Callbacks
-
-Pass typed objects, not callback parades. Child widgets receive a single typed object that encapsulates all the data they need.
-
-**Detection signals:**
-- Widgets have 4+ parameters beyond key and callbacks
-- Boolean flags being passed through multiple widget layers
-- Changing a child's behavior requires changing the parent's call site
-- Parameters that are only used in some conditions
-
-**Incorrect (flag parade):**
-
-```dart
-QuestClaimButton(
-  quest: quest,
-  onSuccess: onClaimSuccess,
-  isExpired: isExpired,
-  isTutorial: isTutorial,
-  bonus: bonus,
-  showMultiplier: showMultiplier,
-  isPremiumUser: isPremiumUser,
-)
-```
-
-**Correct (typed data object):**
-
-```dart
-// Data object encapsulates all context
-sealed class QuestClaimMode {
-  final QuestEntity quest;
-  final RewardBonus? bonus;
-
-  const QuestClaimMode({required this.quest, this.bonus});
-
-  factory QuestClaimMode.fromContext({
-    required QuestEntity quest,
-    required UserEntity? user,
-    required bool isTutorialQuest,
-  }) {
-    // Decision logic centralized here
-    if (quest.isExpired) return QuestClaimModeExpired(quest: quest);
-    if (isTutorialQuest) return QuestClaimModeTutorial(quest: quest);
-    return QuestClaimModeNormal(
-      quest: quest,
-      bonus: user?.applyRewardBonus(quest.reward),
-    );
-  }
-}
-
-// Clean widget API
-QuestClaimButton(
-  mode: QuestClaimMode.fromContext(quest: quest, user: user, isTutorial: isTutorial),
-  onSuccess: onClaimSuccess,
-)
-```
-
-**Why it matters:**
-- Child widget's API is stable even as requirements change
-- Parent doesn't need to know child's internal decision logic
-- Data dependencies are explicit in the mode type
-- Easier to test: create mode objects directly
-
-**Detection questions:**
-- Do widgets have 4+ parameters beyond key and callbacks?
-- Are boolean flags being passed through multiple widget layers?
-- Does changing a child's behavior require changing the parent's call site?
-- Are there parameters that are only used in some conditions?

package/skills/flutter-senior-review/principles/dependencies-provider-tree.md

@@ -1,85 +0,0 @@
----
-title: Provider Tree Architecture
-category: dependencies
-impact: MEDIUM
-impactDescription: Clarifies data flow
-tags: riverpod, provider, architecture, dependencies
----
-
-## Provider Tree Architecture
-
-Root -> branch -> leaf hierarchy for providers. Clear mental model of which providers depend on which.
-
-**Mental model:**
-- **Root providers**: Match app lifecycle, never disposed. Hold core entities (user, games, quests). Referenced from many places. Use `keepAlive: true`.
-- **Branch providers**: Combine/filter/transform core data. May become "core" as app grows (e.g., `squadQuestsProvider`).
-- **Leaf providers**: Screen-specific or ephemeral. Depend on branches, rarely watched by other providers.
-
-**Detection signals:**
-- Can't draw the provider dependency graph as a tree
-- Circular or confusing dependency chains
-- "Leaf" providers being watched by other providers
-- Provider doing too much (should split into root + branch)
-
-**Incorrect (flat, tangled):**
-
-```dart
-// Hard to trace what depends on what
-final userProvider = ...;
-final questsProvider = ...; // watches userProvider
-final gamesProvider = ...; // watches userProvider
-final filteredQuestsProvider = ...; // watches questsProvider, gamesProvider, some other provider
-final screenStateProvider = ...; // watches 5 different providers
-```
-
-**Correct (tree structure):**
-
-```dart
-// Root (core entities, keepAlive: true)
-@Riverpod(keepAlive: true)
-Future<User> user(Ref ref) => ref.watch(authProvider.future).then((auth) => auth.user);
-
-@Riverpod(keepAlive: true)
-Future<List<Quest>> quests(Ref ref) async {
-  final user = await ref.watch(userProvider.future);
-  if (user == null) return [];
-  return ref.watch(questsApiProvider).fetchQuests(user.id);
-}
-
-// Branch (derived/filtered, may become core as app grows)
-@riverpod
-Future<List<Quest>> squadQuests(Ref ref) async {
-  final quests = await ref.watch(questsProvider.future);
-  return quests.where((q) => q.type == QuestType.squad).toList();
-}
-
-@riverpod
-Future<List<Quest>> soloQuests(Ref ref) async {
-  final quests = await ref.watch(questsProvider.future);
-  return quests.where((q) => q.type == QuestType.solo).toList();
-}
-
-// Leaf (screen-specific, ephemeral)
-@riverpod
-class SquadQuestScreenState extends _$SquadQuestScreenState {
-  @override
-  FutureOr<ScreenState> build() async {
-    // Only watches branch providers
-    final quests = await ref.watch(squadQuestsProvider.future);
-    return ScreenState(quests: quests);
-  }
-  // Never watched by other providers
-}
-```
-
-**Why it matters:**
-- Clear mental model of data flow
-- Predictable rebuild scope
-- Easier to add new derived providers
-- Natural place for each piece of logic
-
-**Detection questions:**
-- Can you draw the provider dependency graph as a tree?
-- Are there circular or confusing dependency chains?
-- Are "leaf" providers being watched by other providers?
-- Is a provider doing too much (should it split into root + branch)?

package/skills/flutter-senior-review/principles/dependencies-temporal-coupling.md

@@ -1,97 +0,0 @@
----
-title: Temporal Coupling
-category: dependencies
-impact: MEDIUM
-impactDescription: Catches misuse at compile time
-tags: builder-pattern, type-state, initialization, sequence
----
-
-## Temporal Coupling (Enforce Sequences)
-
-Enforce operation sequences via types, not documentation. Make it impossible to call methods in the wrong order.
-
-**Detection signals:**
-- Methods that must be called before others
-- Comments like "must call X first" or "call after Y"
-- Objects can be in an "invalid" state between operations
-- Tests have setup steps that could be forgotten
-
-**Incorrect (implicit sequence):**
-
-```dart
-class PaymentProcessor {
-  void init() { ... }
-  void setAmount(int amount) { ... }
-  void setCustomer(Customer c) { ... }
-  Future<void> process() { ... } // Must call init, setAmount, setCustomer first!
-}
-
-// Easy to misuse:
-final processor = PaymentProcessor();
-processor.process(); // Boom - forgot to init
-```
-
-**Correct (builder pattern):**
-
-```dart
-class PaymentBuilder {
-  int? _amount;
-  Customer? _customer;
-
-  PaymentBuilder withAmount(int amount) {
-    _amount = amount;
-    return this;
-  }
-
-  PaymentBuilder withCustomer(Customer c) {
-    _customer = c;
-    return this;
-  }
-
-  Payment build() {
-    assert(_amount != null && _customer != null);
-    return Payment(amount: _amount!, customer: _customer!);
-  }
-}
-
-// Usage is clear
-final payment = PaymentBuilder()
-    .withAmount(100)
-    .withCustomer(customer)
-    .build();
-```
-
-**Correct (type-state pattern):**
-
-```dart
-// Types enforce valid sequences
-class UninitializedProcessor {
-  InitializedProcessor init(Config config) => InitializedProcessor(config);
-}
-
-class InitializedProcessor {
-  final Config _config;
-  InitializedProcessor(this._config);
-
-  Future<Result> process(int amount, Customer c) async {
-    // Can only be called on initialized processor
-    return _processPayment(amount, c);
-  }
-}
-
-// Misuse is a compile error
-final processor = UninitializedProcessor();
-processor.process(100, customer); // Error: process is not defined on UninitializedProcessor
-```
-
-**Why it matters:**
-- Compiler catches misuse, not runtime
-- Self-documenting: types show valid sequences
-- Impossible to forget required steps
-- Easier onboarding for new developers
-
-**Detection questions:**
-- Are there methods that must be called before others?
-- Are there comments like "must call X first" or "call after Y"?
-- Can objects be in an "invalid" state between operations?
-- Do tests have setup steps that could be forgotten?

package/skills/flutter-senior-review/principles/pragmatism-consistent-error-handling.md

@@ -1,130 +0,0 @@
----
-title: Consistent Error Handling
-category: pragmatism
-impact: MEDIUM
-impactDescription: Improves UX and debugging
-tags: error-handling, async-value, riverpod, toast
----
-
-## Consistent Error Handling Strategy
-
-One strategy applied everywhere, not ad-hoc try/catch. Use AsyncValue for state management and centralized error presentation.
-
-**Detection signals:**
-- Errors appear differently across screens (toasts vs dialogs vs inline)
-- try/catch blocks scattered in widget code
-- Inconsistent error messaging
-- No standard retry mechanism
-
-**Incorrect (ad-hoc handling):**
-
-```dart
-// Screen 1: Try/catch with toast
-try {
-  await ref.read(saveProvider.notifier).save();
-} catch (e) {
-  ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text('$e')));
-}
-
-// Screen 2: Different pattern
-final result = await ref.read(saveProvider.notifier).save();
-if (result.isError) {
-  showDialog(...); // Different error UI
-}
-
-// Screen 3: No error handling at all
-await ref.read(saveProvider.notifier).save(); // Hope it works!
-```
-
-**Correct (consistent pattern):**
-
-```dart
-// Providers handle errors uniformly with AsyncValue.guard
-@riverpod
-class SaveController extends _$SaveController {
-  @override
-  FutureOr<void> build() => null;
-
-  Future<void> save(Data data) async {
-    state = const AsyncLoading();
-    state = await AsyncValue.guard(() => _repository.save(data));
-    // Error stays in state, not thrown
-    // Success navigates or shows confirmation
-    if (state.hasValue) {
-      ref.invalidate(dataProvider);
-    }
-  }
-}
-
-// Extension for centralized error listening
-extension WidgetRefEx on WidgetRef {
-  void listenOnError<T>(
-    ProviderListenable<AsyncValue<T>> provider, {
-    bool Function(Object error)? ignoreIf,
-  }) {
-    listen(provider, (_, next) {
-      next.whenOrNull(
-        error: (error, _) {
-          if (ignoreIf?.call(error) == true) return;
-          AppToast.showError(context, error.toString());
-        },
-      );
-    });
-  }
-}
-
-// Screens use consistent pattern
-Widget build(context, ref) {
-  // Centralized error listening - shows toast on any error
-  ref.listenOnError(saveProvider);
-
-  final saveState = ref.watch(saveProvider);
-
-  return AppPrimaryButton(
-    isLoading: saveState.isLoading,
-    onPressed: () => ref.read(saveProvider.notifier).save(data),
-    child: Text('Save'),
-  );
-}
-```
-
-**For first-load errors (need retry UI):**
-
-```dart
-Widget build(context, ref) {
-  final dataState = ref.watch(dataProvider);
-
-  return dataState.when(
-    data: (data) => DataContent(data: data),
-    loading: () => const AppLoadingIndicator(),
-    error: (error, _) => Center(
-      child: Column(
-        mainAxisAlignment: MainAxisAlignment.center,
-        children: [
-          Icon(Icons.error_outline, size: 64, color: context.colorScheme.error),
-          const SizedBox(height: 16),
-          Text(LocaleKeys.common_error.tr()),
-          const SizedBox(height: 16),
-          FilledButton.icon(
-            onPressed: () => ref.invalidate(dataProvider),
-            icon: const Icon(Icons.refresh),
-            label: Text(LocaleKeys.common_retry.tr()),
-          ),
-        ],
-      ),
-    ),
-  );
-}
-```
-
-**Why it matters:**
-- Users get consistent experience
-- Developers follow one pattern
-- Error states are explicit and testable
-- Retry logic is standardized
-
-**Detection questions:**
-- Do errors appear the same way across all screens?
-- Are there try/catch blocks in widget code?
-- Is error messaging consistent (toasts vs dialogs vs inline)?
-- Is there a standard retry mechanism?

package/skills/flutter-senior-review/principles/pragmatism-speculative-generality.md

@@ -1,91 +0,0 @@
----
-title: Speculative Generality
-category: pragmatism
-impact: MEDIUM
-impactDescription: Reduces unnecessary complexity
-tags: abstraction, yagni, over-engineering, interfaces
----
-
-## Speculative Generality (Know When NOT to Abstract)
-
-Don't abstract until 2-3 concrete cases exist. Build for today's requirements; extract abstractions when you have real examples.
-
-**Detection signals:**
-- Interface with only one implementation
-- Factory that only creates one type
-- Configuration options no one uses
-- Abstraction added "in case we need it later"
-
-**Incorrect (premature abstraction):**
-
-```dart
-// "We might need different storage backends someday"
-abstract class StorageStrategy {
-  Future<void> save(String key, String value);
-  Future<String?> load(String key);
-}
-
-class LocalStorageStrategy implements StorageStrategy {
-  @override
-  Future<void> save(String key, String value) => _prefs.setString(key, value);
-
-  @override
-  Future<String?> load(String key) => _prefs.getString(key);
-}
-
-class StorageFactory {
-  static StorageStrategy create(StorageType type) => switch (type) {
-    StorageType.local => LocalStorageStrategy(), // Only one ever used
-  };
-}
-
-// "We might need to support multiple payment providers"
-abstract class PaymentProvider { ... }
-class StripeProvider implements PaymentProvider { ... } // Only one exists
-```
-
-**Correct (direct usage):**
-
-```dart
-// Just use the thing directly
-class LocalStorage {
-  final SharedPreferences _prefs;
-
-  LocalStorage(this._prefs);
-
-  Future<void> save(String key, String value) => _prefs.setString(key, value);
-  Future<String?> load(String key) async => _prefs.getString(key);
-}
-
-// When you ACTUALLY need a second implementation, THEN abstract
-// The refactoring is straightforward and you'll know the right abstraction
-// because you have concrete examples of the variation
-```
-
-**When TO abstract:**
-
-```dart
-// You have 2+ real implementations with actual differences
-abstract class AuthProvider {
-  Future<User> signIn();
-  Future<void> signOut();
-}
-
-class GoogleAuthProvider implements AuthProvider { ... }
-class AppleAuthProvider implements AuthProvider { ... }
-class EmailAuthProvider implements AuthProvider { ... }
-
-// The abstraction is earned - you know exactly what varies
-```
-
-**Why it matters:**
-- Less code to maintain
-- Abstractions based on real needs fit better
-- Easier to understand: no indirection to trace
-- YAGNI: You Aren't Gonna Need It
-
-**Detection questions:**
-- Is there an interface with only one implementation?
-- Is there a factory that only creates one type?
-- Are there configuration options no one uses?
-- Was this abstraction added "in case we need it later"?

package/skills/flutter-senior-review/principles/state-data-clumps.md

@@ -1,64 +0,0 @@
----
-title: Data Clumps to Records
-category: state
-impact: MEDIUM-HIGH
-impactDescription: Reduces parameter proliferation
-tags: record, typedef, data-modeling, parameters
----
-
-## Data Clumps to Records
-
-Group parameters that travel together into typed objects (records or classes).
-
-**Detection signals:**
-- Same 3+ parameters appear in multiple function signatures
-- Parameters are logically related (always used together)
-- Adding a new related field requires updating many signatures
-- Bugs from passing parameters in the wrong order
-
-**Incorrect (repeated parameter groups):**
-
-```dart
-void showReward(int baseReward, int? boostedReward, int? multiplier) { ... }
-void displayBadge(int baseReward, int? boostedReward, int? multiplier) { ... }
-void logClaim(int baseReward, int? boostedReward, int? multiplier) { ... }
-
-Widget buildReward({
-  required int baseReward,
-  int? boostedReward,
-  int? multiplier,
-}) { ... }
-```
-
-**Correct (typed record/class):**
-
-```dart
-// Record for simple data grouping
-typedef RewardBonus = ({int base, int? boosted, int? multiplier});
-
-// Or class if behavior is needed
-class RewardCalculation {
-  final int base;
-  final int? boosted;
-  final int? multiplier;
-
-  bool get hasBonus => multiplier != null;
-  int get displayAmount => boosted ?? base;
-}
-
-// Clean call sites
-void showReward(RewardBonus bonus) { ... }
-Widget buildReward({required RewardBonus bonus}) { ... }
-```
-
-**Why it matters:**
-- Single place to add new related fields
-- Impossible to pass parameters in wrong order
-- Semantic meaning is clear
-- Reduces parameter count everywhere
-
-**Detection questions:**
-- Do the same 3+ parameters appear in multiple function signatures?
-- Are parameters logically related (always used together)?
-- Would adding a new related field require updating many signatures?
-- Are there bugs from passing parameters in the wrong order?

package/skills/flutter-senior-review/principles/state-invalid-states.md

@@ -1,53 +0,0 @@
----
-title: Make Invalid States Unrepresentable
-category: state
-impact: CRITICAL
-impactDescription: Eliminates entire class of bugs
-tags: sealed-class, boolean-flags, state-modeling, type-safety
----
-
-## Make Invalid States Unrepresentable
-
-Replace boolean flag combinations with sealed class hierarchies where each variant represents exactly one valid state.
-
-**Detection signals:**
-- 3+ boolean parameters passed together
-- Same boolean checks repeated in multiple places
-- if/else chains checking flag combinations
-- Some flag combinations would cause undefined behavior
-
-**Incorrect (boolean flag explosion):**
-
-```dart
-Widget build() {
-  final isLoading = ...;
-  final isExpired = ...;
-  final isTutorial = ...;
-  final hasBonus = ...;
-  // What happens when isTutorial && isExpired?
-  // What about isLoading && hasBonus && isTutorial?
-}
-```
-
-**Correct (sealed class hierarchy):**
-
-```dart
-sealed class ItemMode {
-  const ItemMode();
-}
-final class ItemModeNormal extends ItemMode { ... }
-final class ItemModeTutorial extends ItemMode { ... }
-final class ItemModeExpired extends ItemMode { ... }
-```
-
-**Why it matters:**
-- Compiler enforces exhaustive handling via switch expressions
-- New states added explicitly, not as boolean combinations
-- Impossible to create invalid state combinations
-- Self-documenting: sealed class shows all possible states
-
-**Detection questions:**
-- Are there 3+ boolean parameters being passed together?
-- Do you see the same boolean checks repeated in multiple places?
-- Are there if/else chains checking combinations of flags?
-- Could some flag combinations cause undefined behavior?

package/skills/flutter-senior-review/principles/state-single-source-of-truth.md

@@ -1,68 +0,0 @@
----
-title: Single Source of Truth
-category: state
-impact: HIGH
-impactDescription: Prevents stale data bugs
-tags: state-ownership, provider, derived-state, riverpod
----
-
-## Single Source of Truth (State Ownership)
-
-One owner per state, derive the rest via selectors. Push long-lived state up to providers; keep only ephemeral UI state local.
-
-**Detection signals:**
-- Same data stored in both a provider and local widget state
-- useEffect hooks syncing local state from provider state
-- Two sources of truth could disagree
-- Derived data being cached instead of computed
-
-**Incorrect (duplicated state):**
-
-```dart
-class ItemScreen extends HookConsumerWidget {
-  Widget build(context, ref) {
-    final items = ref.watch(itemsProvider);
-    // Local state duplicating what provider knows
-    final selectedItem = useState<Item?>(null);
-    final isEditing = useState(false);
-
-    // Widget caches a derived value
-    final totalPrice = useState(0);
-    useEffect(() {
-      totalPrice.value = items.fold(0, (sum, i) => sum + i.price);
-    }, [items]);
-  }
-}
-```
-
-**Correct (single owner, derived values):**
-
-```dart
-// Provider owns the state
-@riverpod
-class ItemsController extends _$ItemsController {
-  Item? get selectedItem => state.value?.firstWhereOrNull((i) => i.isSelected);
-  int get totalPrice => state.value?.fold(0, (sum, i) => sum + i.price) ?? 0;
-}
-
-// Widget only has ephemeral UI state
-class ItemScreen extends HookConsumerWidget {
-  Widget build(context, ref) {
-    final items = ref.watch(itemsProvider);
-    final selectedItem = ref.watch(itemsProvider.select((s) => s.selectedItem));
-    final isTextFieldFocused = useState(false); // Truly ephemeral
-  }
-}
-```
-
-**Why it matters:**
-- No "which value is authoritative?" confusion
-- State updates propagate automatically
-- Easier debugging: one place to inspect
-- Prevents stale data bugs
-
-**Detection questions:**
-- Is the same data stored in both a provider and local widget state?
-- Are there useEffect hooks syncing local state from provider state?
-- Could two sources of truth disagree? What happens then?
-- Is there derived data being cached instead of computed?