mindsystem-cc 3.3.2 → 3.5.0

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

@@ -0,0 +1,64 @@
+---
+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

@@ -0,0 +1,53 @@
+---
+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

@@ -0,0 +1,68 @@
+---
+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?

package/skills/flutter-senior-review/principles/state-type-hierarchies.md

@@ -0,0 +1,75 @@
+---
+title: Explicit Type Hierarchies Over Implicit Conventions
+category: state
+impact: HIGH
+impactDescription: Centralizes decision logic
+tags: factory, sealed-class, decision-logic, type-safety
+---
+
+## Explicit Type Hierarchies Over Implicit Conventions
+
+Use factories to encapsulate decision logic. Widgets receive pre-computed decisions, not raw data to interpret.
+
+**Detection signals:**
+- Complex if/else chains determining which widget to render
+- Same decision logic duplicated across multiple widgets
+- Widgets receive data they only use to make decisions (not to display)
+- New requirement would add another boolean parameter
+
+**Incorrect (scattered decision logic):**
+
+```dart
+Widget _buildTrailing(BuildContext context, {required bool isExpired, required bool isTutorial}) {
+  if (quest.status.isClaimable && quest.isExpired) {
+    return QuestClaimButton(quest: quest, isExpired: true);
+  }
+  if (quest.canClaim) {
+    if (isTutorial) {
+      return PulsingGlowWrapper(child: QuestClaimButton(quest: quest, isTutorial: true));
+    }
+    return QuestClaimButton(quest: quest);
+  }
+  return _buildRewardBadge(context);
+}
+```
+
+**Correct (factory with type hierarchy):**
+
+```dart
+sealed class QuestClaimMode {
+  factory QuestClaimMode.fromContext({
+    required QuestEntity quest,
+    required UserEntity? user,
+    required bool isTutorialQuest,
+  }) {
+    if (quest.status.isClaimable && quest.isExpired) {
+      return QuestClaimModeExpired(...);
+    }
+    if (quest.canClaim) {
+      return isTutorialQuest
+        ? QuestClaimModeTutorial(...)
+        : QuestClaimModeNormal(...);
+    }
+    return QuestClaimModePending(...);
+  }
+}
+
+// Widget becomes a simple switch
+Widget _buildTrailing() => switch (claimMode) {
+  QuestClaimModePending() => QuestRewardDisplay(...),
+  QuestClaimModeTutorial() => _wrapWithTutorialEffects(QuestClaimButton(mode: claimMode)),
+  QuestClaimModeNormal() || QuestClaimModeExpired() => QuestClaimButton(mode: claimMode),
+};
+```
+
+**Why it matters:**
+- Decision logic lives in one place (the factory)
+- Widgets receive pre-computed decisions, not raw data to interpret
+- Adding new modes is explicit and compiler-checked
+- Testing is clearer: test the factory, then test each mode's rendering
+
+**Detection questions:**
+- Are there complex if/else chains determining which widget to render?
+- Is the same decision logic duplicated across multiple widgets?
+- Do widgets receive data they only use to make decisions (not to display)?
+- Would a new requirement add another boolean parameter?

package/skills/flutter-senior-review/principles/structure-composition-over-config.md

@@ -0,0 +1,105 @@
+---
+title: Composition Over Configuration
+category: structure
+impact: MEDIUM
+impactDescription: Simplifies widget APIs
+tags: composition, widget-api, god-widget, parameters
+---
+
+## Composition Over Configuration
+
+Small focused widgets over god widgets with many flags. Use builders and slots instead of boolean parameters.
+
+**Detection signals:**
+- Widget has more than 6-8 parameters
+- Boolean parameters that are mutually exclusive
+- Widget is really 3 different widgets pretending to be 1
+- Adding a new variant would require another boolean flag
+
+**Incorrect (god widget):**
+
+```dart
+AppButton(
+  label: 'Submit',
+  isPrimary: true,
+  isSecondary: false,
+  isDestructive: false,
+  isLoading: false,
+  isDisabled: false,
+  showIcon: true,
+  iconPosition: IconPosition.left,
+  size: ButtonSize.medium,
+  // ... 10 more parameters
+)
+```
+
+**Correct (composed widgets):**
+
+```dart
+// Separate widgets for distinct purposes
+class PrimaryButton extends StatelessWidget {
+  final VoidCallback? onPressed;
+  final Widget child;
+  final bool isLoading;
+
+  const PrimaryButton({
+    super.key,
+    required this.onPressed,
+    required this.child,
+    this.isLoading = false,
+  });
+
+  // ...
+}
+
+// Composition for custom layouts
+PrimaryButton(
+  onPressed: handleSubmit,
+  child: Row(
+    mainAxisSize: MainAxisSize.min,
+    children: [
+      Icon(Icons.check),
+      SizedBox(width: 8),
+      Text('Submit'),
+    ],
+  ),
+)
+
+// Or slot-based API for common patterns
+PrimaryButton.icon(
+  icon: Icons.check,
+  label: 'Submit',
+  onPressed: handleSubmit,
+)
+```
+
+**Alternative: Use sealed class for mutually exclusive variants:**
+
+```dart
+sealed class ButtonVariant {
+  const ButtonVariant();
+}
+class PrimaryVariant extends ButtonVariant { ... }
+class SecondaryVariant extends ButtonVariant { ... }
+class DestructiveVariant extends ButtonVariant { ... }
+
+class AppButton extends StatelessWidget {
+  final ButtonVariant variant;
+  final Widget child;
+  final VoidCallback? onPressed;
+
+  // Single widget, but variants are explicit and exhaustive
+}
+```
+
+**Why it matters:**
+- Each widget has one job
+- New variants don't bloat existing widgets
+- Easier to understand and test
+- Flexible: compose for custom needs, use shortcuts for common ones
+
+**Detection questions:**
+- Does this widget have more than 6-8 parameters?
+- Are there boolean parameters that are mutually exclusive?
+- Is this widget really 3 different widgets pretending to be 1?
+- Would adding a new variant require another boolean flag?

package/skills/flutter-senior-review/principles/structure-shared-visual-patterns.md

@@ -0,0 +1,107 @@
+---
+title: Extract Shared Visual Patterns
+category: structure
+impact: MEDIUM-HIGH
+impactDescription: Guarantees visual consistency
+tags: widget-extraction, style-variants, ui-deduplication, decoration
+---
+
+## Extract Shared Visual Patterns
+
+Deduplicate UI with style variants. When similar visual patterns appear 2+ times, extract a shared widget with an enum or sealed class for variants.
+
+**Detection signals:**
+- Similar Container/decoration patterns across multiple widgets
+- Visual elements (colors, padding, borders) vary based on state
+- Design change would require updating multiple files
+- Subtle inconsistencies between similar UI elements
+
+**Incorrect (duplicated patterns):**
+
+```dart
+// In QuestClaimButton
+Container(
+  padding: EdgeInsets.symmetric(horizontal: 16, vertical: 8),
+  decoration: BoxDecoration(
+    color: isExpired ? AppColors.gray400 : AppColors.forge,
+    borderRadius: BorderRadius.circular(20),
+  ),
+  child: Row(children: [Text('grape'), Text('$reward')]),
+)
+
+// In QuestListTile (slightly different)
+Container(
+  padding: EdgeInsets.symmetric(horizontal: 16, vertical: 8),
+  decoration: BoxDecoration(
+    borderRadius: BorderRadius.circular(20),
+    border: Border.all(color: ...),
+  ),
+  child: Row(children: [Text('grape'), Text('$reward')]),
+)
+```
+
+**Correct (shared widget with variants):**
+
+```dart
+enum QuestRewardStyle { filled, outlined, disabled }
+
+class QuestRewardDisplay extends StatelessWidget {
+  final int reward;
+  final QuestRewardStyle style;
+
+  const QuestRewardDisplay({
+    super.key,
+    required this.reward,
+    this.style = QuestRewardStyle.filled,
+  });
+
+  Widget build(context) {
+    return Container(
+      padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
+      decoration: style.buildDecoration(context),
+      child: Row(
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          Text('grape'),
+          const SizedBox(width: 4),
+          Text('$reward', style: style.buildTextStyle(context)),
+        ],
+      ),
+    );
+  }
+}
+
+extension on QuestRewardStyle {
+  BoxDecoration buildDecoration(BuildContext context) => switch (this) {
+    QuestRewardStyle.filled => BoxDecoration(
+      color: AppColors.forge,
+      borderRadius: BorderRadius.circular(20),
+    ),
+    QuestRewardStyle.outlined => BoxDecoration(
+      borderRadius: BorderRadius.circular(20),
+      border: Border.all(color: AppColors.forge),
+    ),
+    QuestRewardStyle.disabled => BoxDecoration(
+      color: AppColors.gray400,
+      borderRadius: BorderRadius.circular(20),
+    ),
+  };
+
+  TextStyle buildTextStyle(BuildContext context) => switch (this) {
+    QuestRewardStyle.disabled => context.textTheme.bodyMedium!.copyWith(color: AppColors.gray600),
+    _ => context.textTheme.bodyMedium!,
+  };
+}
+```
+
+**Why it matters:**
+- Visual consistency is guaranteed
+- Style changes propagate automatically
+- New variants are added in one place
+- Reduces widget file sizes significantly
+
+**Detection questions:**
+- Are there similar Container/decoration patterns across multiple widgets?
+- Do visual elements (colors, padding, borders) vary based on state?
+- Would a design change require updating multiple files?
+- Are there subtle inconsistencies between similar UI elements?

package/skills/flutter-senior-review/principles/structure-wrapper-pattern.md

@@ -0,0 +1,90 @@
+---
+title: Isolate Feature Responsibility (Wrapper Pattern)
+category: structure
+impact: HIGH
+impactDescription: Features become removable
+tags: wrapper, composition, feature-isolation, widget-extraction
+---
+
+## Isolate Feature Responsibility (Wrapper Pattern)
+
+Extract optional feature logic into wrapper components. The wrapper owns all feature-specific state; the core component doesn't know the feature exists.
+
+**Detection signals:**
+- More than 30% of a widget's code dedicated to one optional feature
+- Removing a feature requires deleting scattered lines throughout the file
+- Multiple `if (featureEnabled)` checks spread across the widget
+- State variables only used by one feature
+
+**Incorrect (scattered feature logic):**
+
+```dart
+class QuestListScreen extends HookConsumerWidget {
+  Widget build(context, ref) {
+    // 50 lines of tutorial-specific state management
+    final tutorialKey = useMemoized(GlobalKey.new);
+    final overlayVisible = useState(true);
+    final cutoutRect = useState<Rect?>(null);
+
+    // Tutorial measurement logic mixed with list logic
+    useEffect(() {
+      if (isTutorialActive) {
+        // 30 lines of tutorial position measurement
+      }
+    });
+
+    // Main list rendering polluted with tutorial checks
+    return Stack(
+      children: [
+        questList,
+        if (showTutorialOverlay) TutorialOverlay(...),
+      ],
+    );
+  }
+}
+```
+
+**Correct (wrapper pattern):**
+
+```dart
+// Tutorial logic fully encapsulated
+class TutorialQuestSpotlight extends HookConsumerWidget {
+  final Widget Function(BuildContext, {GlobalKey? tutorialKey}) builder;
+
+  Widget build(context, ref) {
+    // All tutorial state lives here
+    final tutorialKey = useMemoized(GlobalKey.new);
+    final overlayVisible = useState(true);
+    final cutoutRect = useState<Rect?>(null);
+
+    // Core list doesn't know tutorials exist
+    return Stack(
+      children: [
+        builder(context, tutorialKey: tutorialKey),
+        if (overlayVisible.value) TutorialOverlay(cutoutRect: cutoutRect.value),
+      ],
+    );
+  }
+}
+
+// Clean core component
+class QuestListScreen extends HookConsumerWidget {
+  Widget build(context, ref) {
+    return TutorialQuestSpotlight(
+      builder: (context, {tutorialKey}) => _buildQuestList(tutorialKey),
+    );
+  }
+}
+```
+
+**Why it matters:**
+- Feature can be disabled/removed by removing one wrapper
+- Core component remains focused and testable
+- Feature logic is cohesive and isolated
+- Multiple features can compose without polluting each other
+
+**Detection questions:**
+- Is more than 30% of a widget's code dedicated to one optional feature?
+- Would removing a feature require deleting scattered lines throughout the file?
+- Are there multiple `if (featureEnabled)` checks spread across the widget?
+- Does the widget have state variables only used by one feature?