mindsystem-cc 3.21.0 → 3.22.1

package/skills/{flutter-senior-review → senior-review}/SKILL.md

@@ -1,23 +1,23 @@
 ---
-name: flutter-senior-review
-description: Review Flutter/Dart code for architectural and structural design issues. Use when reviewing PRs, auditing widget design, evaluating state management, or identifying problems that make code hard to evolve.
+name: senior-review
+description: Review code for architectural and structural design issues across any tech stack. Use when reviewing PRs, auditing component design, evaluating state management, or identifying problems that make code hard to evolve. Optimized for web/fullstack (Next.js, React, Node) but applicable to any language.
 license: MIT
 metadata:
   author: Roland Tolnay
   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.
+  date: February 2026
+  abstract: Tech-agnostic code review framework focused on structural improvements that typical reviews miss. Uses 3 core lenses (State Modeling, Responsibility Boundaries, Abstraction Timing) backed by 11 detailed principles organized into 4 categories. Each principle includes detection signals and reasoning — no code examples, as the model already knows language patterns.
 ---
 
-# Flutter Senior Review
+# 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.
+Senior engineering principles for code across any tech stack. 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
+- Refactoring existing code
 - Writing new features or components
 - Identifying why code feels hard to change
 - Planning structural improvements
@@ -53,9 +53,9 @@ Look for:
 - 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.
+**Senior pattern:** Discriminated unions/enums where each variant is a valid state. Factory functions 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`
+Related principles: `state-invalid-states.md`, `state-type-hierarchies.md`, `state-single-source-of-truth.md`
 
 ### Lens 2: Responsibility Boundaries
 
@@ -63,12 +63,12 @@ Related principles: `state-invalid-states.md`, `state-type-hierarchies.md`, `sta
 
 Look for:
 - Optional feature logic scattered throughout a parent component
-- Widgets with 6+ parameters (doing too much)
+- Components/modules 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.
+**Senior pattern:** Wrapper/decorator components for optional features. Typed data objects instead of flag parades. Each module has one job.
 
-Related principles: `structure-wrapper-pattern.md`, `structure-shared-visual-patterns.md`, `structure-composition-over-config.md`
+Related principles: `structure-feature-isolation.md`, `structure-composition-over-config.md`, `structure-module-cohesion.md`
 
 ### Lens 3: Abstraction Timing
 
@@ -82,34 +82,33 @@ Look for:
 
 **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`
+Related principles: `pragmatism-speculative-generality.md`, `dependencies-data-not-flags.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 |
+| State & Types | 1, 2, 3 | Invalid states, type hierarchies, single source of truth |
+| Structure | 4, 5, 6 | Feature isolation, composition, module cohesion |
+| Dependencies | 7, 8, 9 | Data flow, temporal coupling, API boundary design |
+| Pragmatism | 10, 11 | 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
+- **invalid-states** - Replace boolean flag combinations with discriminated unions/enums
+- **type-hierarchies** - Use factories to encapsulate decision logic in the type system
+- **single-source-of-truth** - One owner per state, derive the rest
 
 ### 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
+- **feature-isolation** - Isolate optional feature logic into wrapper/decorator components
+- **composition-over-config** - Small focused components over god components with many flags
+- **module-cohesion** - Group related logic into cohesive module boundaries
 
 ### Dependencies & Flow
-- **data-not-callbacks** - Pass typed objects, not callback parades
-- **provider-tree** - Root -> branch -> leaf hierarchy for providers
+- **data-not-flags** - Pass typed data objects through layers, not boolean flag parades
 - **temporal-coupling** - Enforce operation sequences via types, not documentation
+- **api-boundary-design** - Typed request/response contracts with validation at boundaries
 
 ### Pragmatism
 - **speculative-generality** - Don't abstract until 2-3 concrete cases exist
@@ -117,20 +116,19 @@ Related principles: `pragmatism-speculative-generality.md`, `dependencies-data-n
 
 ## How to Use
 
-Read individual principle files for detailed explanations and code examples:
+Read individual principle files for detailed explanations:
 
 ```
 principles/state-invalid-states.md
-principles/structure-wrapper-pattern.md
-principles/dependencies-provider-tree.md
+principles/structure-feature-isolation.md
+principles/dependencies-api-boundary-design.md
 ```
 
 Each principle file contains:
-- Brief explanation of why it matters
+- Brief explanation of what to do instead
 - Detection signals (what to look for)
-- Incorrect code example with explanation
-- Correct code example with explanation
-- Why it matters section
+- Why it matters (evolution impact)
+- Senior pattern description
 - Detection questions for self-review
 
 ## Context Gathering
@@ -161,7 +159,7 @@ For the specified target, gather the relevant code:
    - 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
+5. **Formulate concrete suggestions** - Name specific extractions, describe before/after for the highest-impact change
 
 ## Output Format
 
@@ -176,7 +174,7 @@ For the specified target, gather the relevant code:
 #### 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]
+**Suggestion:** [Concrete refactoring - name the types/modules to extract]
 
 #### Medium Impact: [Issue Name]
 [Same structure]
@@ -192,13 +190,26 @@ For the specified target, gather the relevant code:
 **What's your take on these suggestions? Any context I'm missing?**
 ```
 
+After the markdown output, append a YAML summary block for orchestrator parsing:
+
+```yaml
+# review-summary
+findings: [number of findings]
+high_impact: [count]
+medium_impact: [count]
+low_impact: [count]
+top_issue: "[one-line description of highest impact finding]"
+verdict: "clean | minor_issues | needs_refactoring | structural_concerns"
+```
+
 ## 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
+- Suggestions are concrete: specific types/modules named, not vague advice
 - No forced findings - if code is solid, say so
 - User has opportunity to provide context before changes
+- YAML summary block included for orchestrator parsing
 
 ## Full Compiled Document
 

package/skills/senior-review/principles/dependencies-api-boundary-design.md

@@ -0,0 +1,32 @@
+---
+title: API Boundary Design
+category: dependencies
+impact: HIGH
+impactDescription: Prevents invalid data from propagating
+tags: api-contracts, validation, boundaries, request-response
+---
+
+## API Boundary Design
+
+Define typed request/response contracts with validation at system boundaries. Trust internal code; verify external input.
+
+**Detection signals:**
+- API handlers that accept `any` or untyped request bodies
+- Validation logic scattered across business logic instead of at the boundary
+- No shared type between client and server for the same endpoint
+- Error responses that leak internal details (stack traces, database errors)
+- Different endpoints handling the same entity with inconsistent field names
+
+**Why it matters:**
+- Invalid data is caught at the boundary before it reaches business logic
+- Internal code operates on validated, typed data — no defensive checks everywhere
+- Client and server stay in sync through shared types or generated contracts
+- Error responses are consistent and safe for consumers
+
+**Senior pattern:** Validate and parse at the boundary: incoming data is unknown until validated, then flows as typed objects through internal layers. Define request/response types explicitly (schema validation, codegen, or shared type packages). Internal functions receive validated types and trust them — they don't re-validate. Error responses follow a consistent shape with safe, user-facing messages.
+
+**Detection questions:**
+- Do API handlers accept untyped or `any` request bodies?
+- Is validation scattered across business logic instead of concentrated at boundaries?
+- Is there a shared type contract between client and server?
+- Do error responses leak internal details like stack traces?

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

@@ -0,0 +1,32 @@
+---
+title: Data Objects Over Flag Parades
+category: dependencies
+impact: MEDIUM-HIGH
+impactDescription: Stabilizes APIs between layers
+tags: data-objects, flags, coupling, api-design
+---
+
+## Data Objects Over Flag Parades
+
+Pass typed data objects through layers instead of boolean flag parades that couple caller to implementation.
+
+**Detection signals:**
+- Functions/components have 4+ boolean or primitive parameters beyond core data
+- Boolean flags being passed through multiple layers unchanged
+- Changing a child's behavior requires changing every intermediate caller's signature
+- Parameters that are only used in some conditions
+- Same group of parameters appears in multiple function signatures
+
+**Why it matters:**
+- Consumer's API is stable even as internal requirements change
+- Callers don't need to know the consumer's internal decision logic
+- Data dependencies are explicit in the object's type
+- Easier to test: create data objects directly without reconstructing call chains
+
+**Senior pattern:** Group related parameters into a typed data object (interface, type, struct, record). The object carries everything the consumer needs to make its own decisions. The caller constructs the object from available context — if construction is complex, use a factory. The consumer's public API accepts the data object, not individual flags.
+
+**Detection questions:**
+- Are there 4+ boolean/primitive parameters being passed alongside core data?
+- Are flags being threaded through multiple layers without being used in intermediate ones?
+- Would changing a child's behavior require updating every caller's signature?
+- Do the same parameter groups appear in multiple function signatures?

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

@@ -0,0 +1,32 @@
+---
+title: Temporal Coupling
+category: dependencies
+impact: MEDIUM
+impactDescription: Catches misuse at compile time
+tags: builder-pattern, type-state, initialization, sequence
+---
+
+## Temporal Coupling
+
+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
+- Init/setup methods that must run before the object is usable
+
+**Why it matters:**
+- Compiler catches misuse, not runtime errors
+- Self-documenting: types show valid sequences
+- Impossible to forget required steps
+- Easier onboarding: the API guides you through the correct order
+
+**Senior pattern:** Use the builder pattern (fluent API that accumulates required state before producing the final object) or the type-state pattern (each step returns a different type that only exposes the next valid operation). For simpler cases, require all necessary data in the constructor so an object is always valid from creation.
+
+**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/senior-review/principles/pragmatism-consistent-error-handling.md

@@ -0,0 +1,32 @@
+---
+title: Consistent Error Handling
+category: pragmatism
+impact: MEDIUM
+impactDescription: Improves UX and debugging
+tags: error-handling, try-catch, error-boundaries, consistency
+---
+
+## Consistent Error Handling
+
+Adopt one error handling strategy and apply it everywhere. Ad-hoc try/catch leads to inconsistent UX and swallowed errors.
+
+**Detection signals:**
+- Errors appear differently across screens (toasts vs dialogs vs inline vs nothing)
+- try/catch blocks scattered in component/handler code with different recovery strategies
+- Inconsistent error messaging (raw exceptions shown to users in some places)
+- No standard retry mechanism
+- Some code paths silently swallow errors with empty catch blocks
+
+**Why it matters:**
+- Users get a consistent experience when things go wrong
+- Developers follow one pattern — no decision fatigue per error site
+- Error states are explicit and testable, not hidden in catch blocks
+- Debugging is faster: errors flow through a known path
+
+**Senior pattern:** Establish a single error handling strategy for the project: errors flow through a known path (Result types, error boundaries, middleware, or global handlers) and surface to users through one consistent mechanism. Individual call sites don't decide how to present errors — they report them, and the strategy handles presentation. Empty catch blocks are banned; if an error is truly ignorable, document why.
+
+**Detection questions:**
+- Do errors appear differently across different screens or endpoints?
+- Are try/catch blocks scattered with different recovery strategies?
+- Are there empty catch blocks that silently swallow errors?
+- Is there a standard, documented error handling strategy for the project?

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

@@ -0,0 +1,32 @@
+---
+title: Speculative Generality
+category: pragmatism
+impact: MEDIUM
+impactDescription: Reduces unnecessary complexity
+tags: abstraction, yagni, over-engineering, interfaces
+---
+
+## Speculative Generality
+
+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"
+- Generic type parameters that are always the same concrete type
+
+**Why it matters:**
+- Less code to maintain and less indirection to trace
+- Abstractions based on real needs fit better than guesses
+- Easier to understand: concrete code is simpler than abstract code
+- When you do need the abstraction, you'll know the right shape because you have concrete examples
+
+**Senior pattern:** Write concrete code for the first case. When the second or third case appears, you'll see the real variation axis and can extract the right abstraction. The refactoring from concrete to abstract is straightforward — but the reverse (removing a premature abstraction) is painful because code depends on the abstraction's shape.
+
+**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/senior-review/principles/state-invalid-states.md

@@ -0,0 +1,33 @@
+---
+title: Make Invalid States Unrepresentable
+category: state
+impact: CRITICAL
+impactDescription: Eliminates entire class of bugs
+tags: discriminated-union, boolean-flags, state-modeling, type-safety
+---
+
+## Make Invalid States Unrepresentable
+
+Replace boolean flag combinations with discriminated unions/enums 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
+- State represented as string literals compared with `===`
+
+**Why it matters:**
+- Compiler/type checker enforces exhaustive handling of all states
+- New states are added explicitly, not as boolean combinations
+- Impossible to create invalid state combinations at the type level
+- Self-documenting: the union/enum shows all possible states in one place
+
+**Senior pattern:** Define a discriminated union (TypeScript), enum with associated data (Rust/Swift), or sealed interface (Kotlin/Java) where each variant carries only the data relevant to that state. Use exhaustive pattern matching (switch/match) so the compiler flags unhandled cases when a new variant is added.
+
+**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?
+- Would adding a new state require updating multiple scattered conditionals?

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

@@ -0,0 +1,32 @@
+---
+title: Single Source of Truth
+category: state
+impact: HIGH
+impactDescription: Prevents stale data bugs
+tags: state-management, derived-state, duplication, synchronization
+---
+
+## Single Source of Truth
+
+One owner per piece of state. Derive everything else via selectors, computed properties, or transformations — never duplicate.
+
+**Detection signals:**
+- Same data stored in both global state and local component state
+- Effect hooks syncing local state from global state
+- Two sources of truth that could disagree
+- Derived data being cached in state instead of computed on access
+- Manual synchronization logic between stores or contexts
+
+**Why it matters:**
+- No "which value is authoritative?" confusion
+- State updates propagate automatically through derivations
+- Easier debugging: one place to inspect each piece of state
+- Eliminates stale data bugs caused by desynchronized copies
+
+**Senior pattern:** Identify the single authoritative owner for each piece of state. All other consumers read from that owner or derive values from it. Local component state is reserved for truly ephemeral UI concerns (focus, hover, animation progress) that no other component needs. If two components need the same state, lift it to a shared owner rather than syncing copies.
+
+**Detection questions:**
+- Is the same data stored in both a global store and local component state?
+- Are there effect hooks whose sole purpose is syncing one state source to another?
+- Could two sources of truth disagree? What happens when they do?
+- Is derived data being cached in state instead of computed from the source?

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

@@ -0,0 +1,32 @@
+---
+title: Explicit Type Hierarchies
+category: state
+impact: HIGH
+impactDescription: Centralizes decision logic
+tags: factory, type-system, decision-logic, pattern-matching
+---
+
+## Explicit Type Hierarchies
+
+Encode decision logic in the type system using factories, not scattered if/else chains across components.
+
+**Detection signals:**
+- Complex if/else chains determining which component to render or which path to take
+- Same decision logic duplicated across multiple modules
+- Components receive data they only use to make decisions (not to display or process)
+- New requirement would add another boolean parameter
+- Switch statements on string values or numeric codes
+
+**Why it matters:**
+- Decision logic lives in one place (the factory)
+- Consumers receive pre-computed decisions, not raw data to interpret
+- Adding new variants is explicit and type-checked
+- Testing is clearer: test the factory, then test each variant's behavior
+
+**Senior pattern:** Create a factory function or static method that takes raw inputs and returns a typed variant. The factory is the single place where decision logic lives. Consumers pattern-match on the result and handle each variant — they never inspect raw data to make decisions themselves.
+
+**Detection questions:**
+- Are there complex if/else chains determining behavior scattered across components?
+- Is the same decision logic duplicated in multiple places?
+- Do components receive data they only use to decide what to do?
+- Would a new requirement add another boolean parameter to existing interfaces?

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

@@ -0,0 +1,32 @@
+---
+title: Composition Over Configuration
+category: structure
+impact: MEDIUM
+impactDescription: Simplifies component APIs
+tags: composition, god-component, flags, single-responsibility
+---
+
+## Composition Over Configuration
+
+Build focused components that compose together instead of god components with many boolean flags.
+
+**Detection signals:**
+- Component has more than 6-8 parameters/props
+- Boolean parameters that are mutually exclusive
+- Component is really 3 different components pretending to be 1
+- Adding a new variant would require another boolean flag
+- Conditionals inside the component that render entirely different structures
+
+**Why it matters:**
+- Each component has one job and is easy to understand
+- New variants don't bloat existing components
+- Easier to test: focused inputs and outputs
+- Flexible: compose for custom needs, use shortcuts for common ones
+
+**Senior pattern:** Split the god component into focused units, each handling one variant or concern. Provide composition points (children/slots/render props) for flexibility. For common combinations, offer convenience wrappers that compose the focused units — but the building blocks remain available for custom needs.
+
+**Detection questions:**
+- Does this component have more than 6-8 parameters?
+- Are there boolean parameters that are mutually exclusive?
+- Is this component really multiple components pretending to be one?
+- Would adding a new variant require another boolean flag?

package/skills/senior-review/principles/structure-feature-isolation.md

@@ -0,0 +1,32 @@
+---
+title: Isolate Feature Responsibility
+category: structure
+impact: HIGH
+impactDescription: Features become removable
+tags: wrapper, decorator, feature-isolation, composition
+---
+
+## Isolate Feature Responsibility
+
+Extract optional feature logic into wrapper/decorator components. The wrapper owns all feature-specific state; the core component doesn't know the feature exists.
+
+**Detection signals:**
+- More than 30% of a component's code dedicated to one optional feature
+- Removing a feature requires deleting scattered lines throughout the file
+- Multiple `if (featureEnabled)` checks spread across the component
+- State variables only used by one feature mixed with core state
+- Feature-specific imports polluting the core module
+
+**Why it matters:**
+- Feature can be disabled/removed by removing one wrapper
+- Core component remains focused and testable
+- Feature logic is cohesive and isolated in one place
+- Multiple features compose without polluting each other
+
+**Senior pattern:** Move all feature-specific state, effects, and rendering into a wrapper/decorator component that wraps the core. The wrapper provides feature context to the core through a render prop, slot, or composition pattern. The core component has zero awareness of the feature — it renders its own concern and accepts optional enhancement points.
+
+**Detection questions:**
+- Is more than 30% of a component'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 component?
+- Does the component have state variables only used by one feature?

package/skills/senior-review/principles/structure-module-cohesion.md

@@ -0,0 +1,32 @@
+---
+title: Module Cohesion
+category: structure
+impact: MEDIUM-HIGH
+impactDescription: Changes stay contained to one module
+tags: cohesion, boundaries, feature-folders, colocation
+---
+
+## Module Cohesion
+
+Group related logic into cohesive module boundaries so that a single feature change touches one module, not many.
+
+**Detection signals:**
+- A feature's logic is spread across 4+ directories by technical layer (routes/, models/, services/, utils/)
+- Changing one feature requires touching files in many unrelated folders
+- Related types, helpers, and constants live far from the code that uses them
+- Shared utility files that grow unbounded because "everything needs it"
+- Circular dependencies between modules
+
+**Why it matters:**
+- Feature changes are contained: one module to understand, one module to test
+- Dependencies between modules are explicit and minimal
+- Easier to extract, replace, or delete a feature entirely
+- New developers can navigate by feature, not by guessing which technical layer holds what
+
+**Senior pattern:** Organize by feature/domain first, technical layer second. Each feature module contains its types, logic, and tests colocated. Shared utilities exist only when genuinely used across 3+ features — otherwise the "utility" belongs in the feature that uses it. Module boundaries are enforced by explicit public APIs (barrel files, index exports) that hide internal structure.
+
+**Detection questions:**
+- Does changing one feature require touching files in many unrelated directories?
+- Is related logic (types, helpers, constants) colocated with the code that uses it?
+- Are there shared utility files that grow unbounded?
+- Can you describe what each module "owns" in one sentence?