@augmentcode/ag-redux-toolkit
Version:
Redux + Saga state management for Svelte apps — designed for AI agents. Includes runtime TypeScript source, AI skills, and reference documentation for robust, observable, high-performance state management.
214 lines (172 loc) • 7.04 kB
Markdown
---
name: svelte/migration/assessment
description: >-
Inventory existing Svelte stores and $state/$derived runes; classify each
store as state / derived / side effects, list consumers, and decide whether
it moves to Redux (shared) or stays as component-local state using the
decision framework. First step of any migration to ag-redux-toolkit.
type: sub-skill
requires:
- svelte
- svelte/migration
triggers:
- audit stores
- classify store
- migration inventory
- shared or local
---
# Migration — Assessment Phase
> Before writing any code, inventory the current state management and decide what moves to Redux.
## 1. Identify All Stores
Use repository searches such as `find src/ -name "*.store.svelte.ts" -o -name "*.store.ts"`, `grep -rn "writable\|readable\|derived" src/ --include="*.ts" --include="*.svelte"`, and `grep -rn '\$state\|\$derived' src/ --include="*.store.svelte.ts"`. Record results as structured assessment evidence so downstream skills can consume them.
## 2. Classify Each Store
For each store file, determine:
1. **What state does it hold?** List all `writable()`, `$state`, or reactive fields
2. **What derived values exist?** List all `derived()`, `$derived`, getters
3. **What side effects exist?** localStorage, fetch, event listeners, timers, IPC
4. **Who consumes it?** Which components import and use this store?
5. **Is it shared or local?** Used by multiple components, or just one?
## 3. Decision Framework
### Move to Redux (shared state)
- State read or written by **multiple components**
- State that **persists** across navigation or page changes
- State involved in **async operations** (API calls, timers, debouncing)
- State that **drives business logic** or cross-feature coordination
- State **synced** with external sources (localStorage, server, IPC)
### Keep as Component-Local State
- **Ephemeral UI state**: hover, focus, open/closed toggles, scroll position
- State that only matters while **one component is mounted**
- State that is **not shared, persisted, or part of business logic**
- Form field values used only within a single form component
**When in doubt → move to Redux.**
## 4. Output of the Assessment
Produce a per-store table so you can order the migration (simplest / most isolated slice first — see `../SKILL.md` for the recommended order and `../setup/SKILL.md` for the bootstrap that must be done before the first slice):
| Store file | State fields | Derived | Side effects | Consumers | Verdict |
| --- | --- | --- | --- | --- | --- |
| cart.store.svelte.ts | items, total | count | localStorage sync | Cart, Header, Checkout | Redux |
| tooltip.store.svelte.ts | open | — | — | Tooltip only | Local |
Downstream skills consume this table:
- `svelte/migration/writable-stores` — for every `writable` / `$state` field
- `svelte/migration/derived-stores` — for every `derived` / `$derived`
- `svelte/migration/side-effects` — for every side effect in the table
- `svelte/migration/component-migration` — for the consumers column
- `svelte/migration/cleanup` — to confirm deletion order
## Examples in This Skill
- Added: assessment record type; shared writable verdict; component-local verdict; derived selector candidate; side-effect saga candidate; bad local-UI overmigration verdict.
- Retained: none (this assessment skill previously had no JS/TS examples).
## Assessment Examples
### 1. Capture inventory as structured evidence
```typescript
type StorePrimitive = "writable" | "readable" | "derived" | "$state" | "$derived" | "$effect";
type MigrationVerdict = "redux" | "local";
type StoreInventoryRecord = {
file: string;
primitives: StorePrimitive[];
stateFields: string[];
derivedValues: string[];
sideEffects: string[];
consumers: string[];
verdict: MigrationVerdict;
nextSkills: string[];
};
const cartInventory: StoreInventoryRecord = {
file: "src/lib/stores/cart.store.svelte.ts",
primitives: ["writable", "derived", "$effect"],
stateFields: ["items"],
derivedValues: ["total", "itemCount"],
sideEffects: ["localStorage sync"],
consumers: ["Cart.svelte", "Header.svelte", "Checkout.svelte"],
verdict: "redux",
nextSkills: ["writable-stores", "derived-stores", "side-effects", "component-migration"],
};
```
### 2. Classify shared writable state as Redux-owned
```typescript
type AssessmentInput = {
consumers: string[];
persists: boolean;
asyncDriven: boolean;
businessLogic: boolean;
};
function classifyState(input: AssessmentInput): "redux" | "local" {
return input.consumers.length > 1 || input.persists || input.asyncDriven || input.businessLogic
? "redux"
: "local";
}
export const cartVerdict = classifyState({
consumers: ["Cart.svelte", "Header.svelte"],
persists: true,
asyncDriven: false,
businessLogic: true,
});
```
### 3. Keep ephemeral component state local
```typescript
type LocalStateFinding = {
file: string;
field: string;
reason: "single-component" | "ephemeral-ui";
replacement: "component-local-state";
};
export const tooltipFinding: LocalStateFinding = {
file: "src/lib/stores/tooltip.store.svelte.ts",
field: "open",
reason: "ephemeral-ui",
replacement: "component-local-state",
};
```
### 4. Route derived values to selector migration
```typescript
type DerivedFinding = {
source: string;
dependencies: string[];
targetSelector: string;
composeWithSelect: boolean;
};
export const cartTotalFinding: DerivedFinding = {
source: "derived(items, ($items) => sumCart($items))",
dependencies: ["items"],
targetSelector: "selectCartTotal",
composeWithSelect: true,
};
```
### 5. Route side effects to saga migration
```typescript
type SideEffectFinding = {
sourceFile: string;
effect: "fetch" | "timer" | "subscription" | "storage" | "ipc";
triggerAction: string;
targetSaga: string;
};
export const persistenceFinding: SideEffectFinding = {
sourceFile: "src/lib/stores/cart.store.svelte.ts",
effect: "storage",
triggerAction: "cart/setItems",
targetSaga: "cartSaga",
};
```
### 6. ❌ Bad: migrate single-component UI state to Redux
```typescript
// ❌ BAD: hover state belongs in the component, not in a Redux slice.
type BadAssessmentRecord = {
file: string;
stateFields: string[];
consumers: string[];
verdict: "redux" | "local";
};
export const badHoverAssessment: BadAssessmentRecord = {
file: "src/lib/stores/card-hover.store.svelte.ts",
stateFields: ["isHovered"],
consumers: ["ProductCard.svelte"],
verdict: "redux",
};
```
## Cases Covered
| Case | Example |
| --- | --- |
| Inventory shape for downstream skills | Capture inventory as structured evidence |
| Shared/persisted/business state | Classify shared writable state as Redux-owned |
| Local-only UI state | Keep ephemeral component state local |
| Derived values | Route derived values to selector migration |
| Effects/subscriptions/storage | Route side effects to saga migration |
| Incorrect overmigration | Bad: migrate single-component UI state to Redux |