mindsystem-cc 3.21.0 → 3.22.1

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

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

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

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

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