mindsystem-cc 3.3.3 → 3.5.0

package/skills/flutter-senior-review/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: flutter-senior-review
+description: Senior engineering principles for Flutter/Dart code reviews. Apply when reviewing, refactoring, or writing Flutter code to identify structural improvements that make code evolvable, not just working.
+license: MIT
+metadata:
+  author: forgeblast
+  version: "1.0.0"
+  date: January 2026
+  abstract: Code review framework focused on structural improvements that typical reviews miss. Uses 3 core lenses (State Modeling, Responsibility Boundaries, Abstraction Timing) backed by 12 detailed principles organized into 4 categories. Each principle includes detection signals, smell examples, senior solutions, and Dart-specific patterns.
+---
+
+# Flutter Senior Review
+
+Senior engineering principles for Flutter/Dart code. Apply when reviewing, refactoring, or writing code to identify structural improvements that make code evolvable, not just working.
+
+## When to Apply
+
+Reference these guidelines when:
+- Reviewing code changes (commits, PRs, patches)
+- Refactoring existing Flutter/Dart code
+- Writing new features or components
+- Identifying why code feels hard to change
+- Planning structural improvements
+
+## Senior Mindset
+
+Junior and mid-level engineers ask: **"Does this code work?"**
+Senior engineers ask: **"How will this code change? What happens when requirements shift?"**
+
+This distinction drives everything. Code that "works" today becomes a liability when:
+- A new state is added and 5 files need coordinated updates
+- A feature toggle requires touching code scattered across the codebase
+- A bug fix in one place breaks assumptions elsewhere
+
+Focus on **structural issues that compound over time** - the kind that turn "add a simple feature" into "refactor half the codebase first."
+
+Do NOT look for:
+- Style preferences or formatting
+- Minor naming improvements
+- "Nice to have" abstractions
+- Issues already covered by linters/analyzers
+
+## Core Lenses
+
+Apply these three lenses to every review. They catch 80% of structural issues.
+
+### Lens 1: State Modeling
+
+**Question:** Can this code represent invalid states?
+
+Look for:
+- Multiple boolean flags (2^n possible states, many invalid)
+- Primitive obsession (stringly-typed status, magic numbers)
+- Same decision logic repeated in multiple places
+
+**Senior pattern:** Sealed classes where each variant is a valid state. Factory methods that encapsulate decision logic. Compiler-enforced exhaustive handling.
+
+Related principles: `state-invalid-states.md`, `state-type-hierarchies.md`, `state-single-source-of-truth.md`, `state-data-clumps.md`
+
+### Lens 2: Responsibility Boundaries
+
+**Question:** If I remove/modify feature X, how many files change?
+
+Look for:
+- Optional feature logic scattered throughout a parent component
+- Widgets with 6+ parameters (doing too much)
+- Deep callback chains passing flags through layers
+
+**Senior pattern:** Wrapper components for optional features. Typed data objects instead of flag parades. Each widget has one job.
+
+Related principles: `structure-wrapper-pattern.md`, `structure-shared-visual-patterns.md`, `structure-composition-over-config.md`
+
+### Lens 3: Abstraction Timing
+
+**Question:** Is this abstraction earned or speculative?
+
+Look for:
+- Interfaces with only one implementation
+- Factories that create only one type
+- "Flexible" config that's never varied
+- BUT ALSO: Duplicated code that should be unified
+
+**Senior pattern:** Abstract when you have 2-3 concrete cases, not before. Extract when duplication causes bugs or drift, not for aesthetics.
+
+Related principles: `pragmatism-speculative-generality.md`, `dependencies-data-not-callbacks.md`
+
+## Principle Categories
+
+| Category | Principles | Focus |
+|----------|------------|-------|
+| State & Types | 1, 3, 6, 10 | Invalid states, type hierarchies, single source of truth, data clumps |
+| Structure | 2, 4, 8 | Feature isolation, visual patterns, composition |
+| Dependencies | 5, 7, 9 | Coupling, provider architecture, temporal coupling |
+| Pragmatism | 11, 12 | Avoiding over-engineering, consistent error handling |
+
+## Quick Reference
+
+### State & Type Safety
+- **invalid-states** - Replace boolean flag combinations with sealed class hierarchies
+- **type-hierarchies** - Use factories to encapsulate decision logic
+- **single-source-of-truth** - One owner per state, derive the rest via selectors
+- **data-clumps** - Group parameters that travel together into typed objects
+
+### Structure & Composition
+- **wrapper-pattern** - Isolate optional feature logic into wrapper components
+- **shared-visual-patterns** - Deduplicate UI with style variants
+- **composition-over-config** - Small focused widgets over god widgets with many flags
+
+### Dependencies & Flow
+- **data-not-callbacks** - Pass typed objects, not callback parades
+- **provider-tree** - Root -> branch -> leaf hierarchy for providers
+- **temporal-coupling** - Enforce operation sequences via types, not documentation
+
+### Pragmatism
+- **speculative-generality** - Don't abstract until 2-3 concrete cases exist
+- **consistent-error-handling** - One strategy applied everywhere, not ad-hoc try/catch
+
+## How to Use
+
+Read individual principle files for detailed explanations and code examples:
+
+```
+principles/state-invalid-states.md
+principles/structure-wrapper-pattern.md
+principles/dependencies-provider-tree.md
+```
+
+Each principle file contains:
+- Brief explanation of why it matters
+- Detection signals (what to look for)
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Why it matters section
+- Detection questions for self-review
+
+## Context Gathering
+
+When asked to review code, first identify the target:
+
+If target is unclear, ask:
+- What code should be reviewed? (specific files, a feature folder, uncommitted changes, a commit, a patch file)
+- Is there a specific concern or area of focus?
+
+For the specified target, gather the relevant code:
+- **Commit**: `git show <commit>`
+- **Patch file**: Read the patch file
+- **Uncommitted changes**: `git diff` and `git diff --cached`
+- **Folder/feature**: Read the relevant files in that directory
+- **Specific file**: Read that file and related files it imports/uses
+
+## Analysis Process
+
+1. **Read thoroughly** - Understand what the code does, not just its structure
+
+2. **Apply the three lenses** - For each lens, note specific instances (or note "no issues found")
+
+3. **Check for additional patterns** - If you notice issues beyond the core lenses, consult the principle files for precise diagnosis
+
+4. **Prioritize by evolution impact**:
+   - High: Will cause cascading changes when requirements shift
+   - Medium: Creates friction but contained to one area
+   - Low: Suboptimal but won't compound
+
+5. **Formulate concrete suggestions** - Name specific extractions, show before/after for the highest-impact change
+
+## Output Format
+
+```markdown
+## Senior Review: [Target]
+
+### Summary
+[1-2 sentences: Overall assessment and the single most important structural opportunity]
+
+### Findings
+
+#### High Impact: [Issue Name]
+**What I noticed:** [Specific code pattern observed]
+**Why it matters:** [How this will cause problems as code evolves]
+**Suggestion:** [Concrete refactoring - name the types/widgets to extract]
+
+#### Medium Impact: [Issue Name]
+[Same structure]
+
+#### Low Impact: [Issue Name]
+[Same structure]
+
+### No Issues Found
+[If a lens revealed no problems, briefly note: "State modeling: No boolean flag combinations or repeated decision logic detected."]
+
+---
+
+**What's your take on these suggestions? Any context I'm missing?**
+```
+
+## Success Criteria
+
+- At least one finding per applicable lens (or explicit "no issues" statement)
+- Each finding tied to evolution impact, not just "could be better"
+- Suggestions are concrete: specific types/widgets named, not vague advice
+- No forced findings - if code is solid, say so
+- User has opportunity to provide context before changes
+
+## Full Compiled Document
+
+For the complete guide with all principles expanded: `AGENTS.md`

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

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

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

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

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

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