@yuaone/core 0.8.4 → 0.9.0

package/dist/skills/skills/languages/r.md

@@ -0,0 +1,80 @@
+## Identity
+- domain: r
+- type: language
+- confidence: 0.88
+
+# R — Error Pattern Reference
+
+Read the exact error message and the call stack from `traceback()`. R errors are often generic ("object not found", "subscript out of bounds") but the call stack reveals which user function triggered the problem.
+
+## Error Code Quick Reference
+- **"object 'x' not found"** — Variable not in scope or wrong environment.
+- **"Error in ... : subscript out of bounds"** — Vector/list index out of range.
+- **"Error in ... : incorrect number of dimensions"** — Subsetting a vector like a matrix.
+- **"NAs introduced by coercion"** — `as.numeric()` or `as.integer()` on non-numeric strings.
+- **"Error in ... : replacement has length zero"** — Empty vector assigned to subset.
+- **"Warning: longer object length is not a multiple of shorter object length"** — Vector recycling mismatch.
+- **"Error: could not find function '...'"** — Package not loaded; function name misspelled.
+- **"there is no package called '...'"** — Package not installed.
+
+## Known Error Patterns
+
+### Object Not Found — Environment Scope
+- **Symptom**: `Error in my_function() : object 'df' not found`; a variable that exists in the global environment is not accessible inside a function.
+- **Cause**: R uses lexical scoping — functions look up variables in the environment where they were defined, not where they are called. A variable in the global environment is not automatically available inside a function that was defined in a different environment. Packages with `NSE` (non-standard evaluation) like `dplyr` use column names as symbols — passing a variable name as a string fails.
+- **Strategy**: 1. Pass variables as function arguments rather than relying on global scope: `my_function(df = my_df)`. 2. For dplyr NSE, use `.data[[var_name]]` to reference columns programmatically: `df %>% mutate(new = .data[[col_name]])`. 3. Use `exists("varname")` to check before accessing. 4. Run `ls()` and `ls(envir = parent.env(environment()))` to inspect available names in current and parent environments. 5. Avoid `attach()` — it causes scope pollution and hard-to-track object-not-found errors.
+- **Tool sequence**: file_read (function definition and call site) → file_edit (add explicit argument passing or .data[[]] notation)
+- **Pitfall**: Do NOT use `<<-` (superassignment) to fix scope issues — it modifies the parent environment and causes state mutation bugs that are very hard to debug.
+
+### Vector Recycling Surprise — Length Mismatch
+- **Symptom**: `Warning: longer object length is not a multiple of shorter object length`; result vector has unexpected values; computation silently proceeds with wrong data.
+- **Cause**: R recycles shorter vectors to match the length of longer ones in element-wise operations. `c(1,2,3,4) + c(10,20)` produces `c(11,22,13,24)` — the shorter vector is recycled. If lengths are not multiples, R issues a warning but still completes the operation.
+- **Strategy**: 1. Treat the recycling warning as an error in data analysis code — check `length(x) == length(y)` before element-wise operations. 2. Use `stopifnot(length(x) == length(y))` as an assertion. 3. For intentional broadcasting of a scalar, document the intent explicitly. 4. In data frame operations, join data frames properly (merge/dplyr join) instead of relying on recycling. 5. Enable warnings as errors during development: `options(warn = 2)`.
+- **Tool sequence**: file_read (arithmetic operations) → file_edit (add length checks or stopifnot assertions)
+- **Pitfall**: Do NOT suppress the recycling warning with `suppressWarnings()` — the result is silently wrong. Fix the length mismatch.
+
+### Factor vs Character Confusion — Unexpected Levels
+- **Symptom**: String operations fail on what appears to be a character column; new values added to a factor become `NA`; `paste()` or `gsub()` produces unexpected output; `nlevels()` returns more levels than values present.
+- **Cause**: Factors store categorical data as integers with level labels. When reading CSV files, `read.csv()` in older R versions (pre-4.0) converts string columns to factors by default. Treating a factor as a character vector causes type errors and unexpected behavior.
+- **Strategy**: 1. Check column types: `str(df)` — factors show as `Factor w/ N levels`. 2. Convert when needed: `as.character(df$column)`. 3. In modern R (>=4.0), `read.csv` uses `stringsAsFactors = FALSE` by default. For older code, add this parameter explicitly. 4. Use `droplevels(df)` to remove unused factor levels after subsetting. 5. When comparing factor values, always compare to the level string: `df$col == "value"`, not `df$col == 1`.
+- **Tool sequence**: shell_exec (`R -e "str(read.csv('file.csv'))"`) → file_read (data loading code) → file_edit (add stringsAsFactors=FALSE or explicit as.character())
+- **Pitfall**: Do NOT convert factors to numeric with `as.numeric(factor_col)` — it gives the integer codes (1, 2, 3...), not the original values. Use `as.numeric(as.character(factor_col))`.
+
+### NA Propagation — Silent Calculation Corruption
+- **Symptom**: `mean(x)` returns `NA`; `sum(x) == NA`; a single missing value silently poisons an entire calculation.
+- **Cause**: `NA` in R propagates through most arithmetic and logical operations — any operation involving `NA` returns `NA`. `mean(c(1, 2, NA, 4))` returns `NA` unless `na.rm = TRUE`.
+- **Strategy**: 1. Always include `na.rm = TRUE` in aggregate functions when NA is acceptable: `mean(x, na.rm = TRUE)`, `sum(x, na.rm = TRUE)`. 2. Check for NAs explicitly: `any(is.na(x))` or `sum(is.na(x))`. 3. Decide on NA handling strategy upfront: drop rows (`na.omit(df)`), impute, or flag. 4. Use `complete.cases(df)` to subset to rows with no NAs. 5. For logical operations, `NA | TRUE == TRUE` but `NA & FALSE == FALSE` — be aware of three-valued logic.
+- **Tool sequence**: grep (`mean(`, `sum(`, `max(`, `min(`) → file_read → file_edit (add na.rm = TRUE or explicit NA checks)
+- **Pitfall**: Do NOT use `na.omit()` blindly on a data frame — it removes entire rows if any column has NA, which may discard more data than intended.
+
+### Package Namespace Conflict — :: Required
+- **Symptom**: `Warning: package 'dplyr' masks 'base' function 'filter'`; calling `filter()` calls the wrong function; behavior changes depending on load order of packages.
+- **Cause**: Multiple packages export functions with the same name (e.g., `dplyr::filter` and `stats::filter`, `dplyr::lag` and `stats::lag`). The last loaded package wins the unqualified name. Load order affects which function is called.
+- **Strategy**: 1. Use the `::` operator to explicitly namespace all function calls in production code: `dplyr::filter()`, `stats::filter()`. 2. Check for conflicts after loading packages: `conflicts()` lists all masked names. 3. Use the `conflicted` package which turns masking warnings into errors: `library(conflicted); conflict_prefer("filter", "dplyr")`. 4. At the top of scripts, document which packages are loaded and in what order.
+- **Tool sequence**: shell_exec (`R -e "library(pkg); conflicts()"`) → file_read → file_edit (add :: namespace qualifiers to ambiguous calls)
+- **Pitfall**: Do NOT rely on `library()` load order to resolve namespace conflicts — load order changes between environments and makes code non-reproducible.
+
+### Memory Error — Copying Large Data Frames
+- **Symptom**: `Error: cannot allocate vector of size N Gb`; R crashes or becomes very slow when processing large data frames; `gc()` doesn't help.
+- **Cause**: R uses copy-on-modify semantics — modifying a column in a data frame creates a copy of the entire data frame. Repeated column additions in a loop (`df$new_col <- ...`) can trigger many copies. R also loads entire datasets into RAM.
+- **Strategy**: 1. Use `data.table` for large datasets — it modifies by reference with `:=` operator, avoiding copies. 2. For loops that build data frames, use `lapply` + `do.call(rbind, list)` or `dplyr::bind_rows` instead of growing a data frame in a loop. 3. Use `fread()` from `data.table` for faster CSV loading with lower memory usage. 4. Process data in chunks for very large files. 5. Call `gc()` to force garbage collection after removing large objects with `rm(large_object)`.
+- **Tool sequence**: file_read (data processing loops) → file_edit (replace loop with lapply/bind_rows or convert to data.table)
+- **Pitfall**: Do NOT preallocate a data frame with empty rows and fill by index — it is slower than building a list and converting once at the end.
+
+## Verification
+Run: `Rscript --vanilla your_script.R`
+- No errors or warnings in output.
+- Use `lintr::lint("script.R")` for style and potential bug checks.
+- Run `testthat` tests: `devtools::test()` — all tests pass.
+
+## Validation Checklist
+- [ ] All functions receive data as arguments, not from global environment
+- [ ] `na.rm = TRUE` specified in all aggregate functions where NA is possible
+- [ ] No `stringsAsFactors = TRUE` in data loading (or explicit factor handling)
+- [ ] Vector length equality checked before element-wise operations
+- [ ] Recycling warnings treated as errors during development (`options(warn=2)`)
+- [ ] All ambiguous function calls use `::` namespace qualifier
+- [ ] `conflicted` package used or load order documented
+- [ ] Large data frame operations use `data.table` or `dplyr` instead of loops
+- [ ] `lintr` passes with no errors
+- [ ] No use of `<<-` superassignment in package code

package/dist/skills/skills/languages/react.md

@@ -0,0 +1,86 @@
+## Identity
+- domain: react
+- type: language
+- confidence: 0.9
+
+# React — Hook Rules, Rendering, and Common Errors
+
+Read the full error message and component stack before touching any code.
+
+## Hook Rules (Enforced by eslint-plugin-react-hooks)
+- Call hooks only at the top level of a function component — never inside conditions, loops, or nested functions.
+- Call hooks only from React function components or other custom hooks.
+- Custom hooks must start with `use`.
+- These rules are not style preferences — violating them causes non-deterministic behavior and crashes that are hard to reproduce.
+
+## Known Error Patterns
+
+### Hook Called Conditionally
+- **Symptom**: ESLint error `React Hook "useX" is called conditionally` — or a runtime crash: `Rendered more hooks than during the previous render`
+- **Cause**: Hook call placed inside an `if` block, after an early `return`, or inside a loop. React requires the same hooks to run in the same order on every render.
+- **Strategy**: Move all hook calls to the top of the component function, above any conditional logic. If the hook should only do something conditionally, move the condition inside the hook's callback or pass a flag to the hook.
+- **Tool sequence**: file_read (component) → file_edit (move hook calls above all conditionals)
+- **Pitfall**: Do NOT wrap hook calls in try/catch or ternary expressions. Restructure the component so all hooks run unconditionally.
+
+### Stale Closure in useEffect
+- **Symptom**: Effect reads an old value of state or props. The callback always has the value from the first render regardless of updates.
+- **Cause**: The dependency array is incomplete — it is missing variables that are read inside the effect.
+- **Strategy**: Add every variable read inside the effect body to the dependency array. If adding a function reference creates an infinite loop, wrap the function in `useCallback` with its own deps. If adding an object creates an infinite loop, use `useMemo` or restructure to pass only primitive values.
+- **Tool sequence**: file_read (useEffect block and deps array) → file_edit (add missing deps)
+- **Pitfall**: Do NOT add `// eslint-disable-next-line react-hooks/exhaustive-deps` to suppress the exhaustive-deps warning. Fix the missing dependencies.
+
+### Infinite Re-render Loop
+- **Symptom**: Component re-renders continuously; browser tab becomes unresponsive or crashes.
+- **Cause**: One of: (a) `setState` called unconditionally inside `useEffect` with no deps or with deps that always change, (b) an object or array literal created inline is in the dependency array (new reference every render), (c) parent passes a new object/function prop on every render.
+- **Strategy**: 1. Read every `useEffect` in the component. Find any `setState` call without a guard condition. 2. Check the deps array for inline object/array literals — move them outside the component or wrap in `useMemo`/`useCallback`. 3. If the loop comes from a parent prop, memoize the prop at the parent.
+- **Tool sequence**: file_read (all useEffect blocks) → file_edit (add condition or memoize deps)
+- **Pitfall**: Do NOT add an empty dependency array `[]` to stop the loop without understanding why it loops. That causes stale closure bugs.
+
+### Hydration Mismatch (Next.js / SSR)
+- **Symptom**: `Error: Text content does not match server-rendered HTML` or `Error: Hydration failed because the initial UI does not match what was rendered on the server`
+- **Cause**: Component renders different content on server vs. client. Common sources: `Date.now()`, `Math.random()`, `window` access, browser-only APIs, locale-dependent formatting.
+- **Strategy**: 1. Identify the value that differs between server and client renders. 2. Move it into a `useEffect` with a local state variable — `useEffect` only runs on the client. 3. Render a placeholder or `null` on first render, then update after mount. 4. Use `suppressHydrationWarning` only on elements with genuinely intentional dynamic content such as timestamps.
+- **Tool sequence**: file_read (component) → file_edit (move dynamic value to useEffect + useState)
+- **Pitfall**: Do NOT use `suppressHydrationWarning` as a general fix. It hides real bugs where content genuinely differs.
+
+### Missing key Prop in List
+- **Symptom**: React warning `Each child in a list should have a unique "key" prop`
+- **Cause**: `Array.map()` renders JSX elements without a `key` prop, or key is not unique within the list.
+- **Strategy**: Add a stable, unique `key` to each element. Use the item's ID from data, not the array index.
+- **Tool sequence**: grep (`\.map(`) → file_read (render section) → file_edit (add key prop)
+- **Pitfall**: Do NOT use array index as key when the list can reorder, filter, or have items added or removed. Index keys cause incorrect reconciliation and state bugs.
+
+### Cannot Read Property of Undefined (During Render)
+- **Symptom**: `TypeError: Cannot read properties of undefined (reading 'x')` thrown during render
+- **Cause**: Component accesses a property on a value that is `undefined` or `null` at mount time — typically async data, optional props, or uninitialized store state.
+- **Strategy**: 1. Add a loading/null guard before the access: `if (!data) return null` or `data?.property`. 2. Provide a default value in the prop type or initial state. 3. Never assume async data is available at first render.
+- **Tool sequence**: file_read (render return and prop types) → file_edit (add guard)
+- **Pitfall**: Do NOT add `!` non-null assertion in TypeScript to hide this — the crash will still happen at runtime.
+
+### Context Value Lost After Rerender
+- **Symptom**: Component reads default context value instead of the provided value; context updates do not propagate.
+- **Cause**: Provider is placed too low in the tree, or `value` prop creates a new object every render causing unnecessary re-renders and sometimes missed updates.
+- **Strategy**: 1. Confirm the consuming component is inside the Provider in the tree. 2. Memoize the context value with `useMemo` to prevent new object reference on every render. 3. Split contexts if one high-frequency value is causing all consumers to re-render.
+- **Tool sequence**: file_read (Provider placement) → file_read (consumer component) → file_edit (add useMemo to context value)
+- **Pitfall**: Do NOT create the context value inline in the JSX without memoization — `value={{ foo, bar }}` creates a new object on every render.
+
+### useRef Value Not Triggering Re-render
+- **Symptom**: Component does not update when a `ref.current` value changes.
+- **Cause**: `useRef` mutations do not trigger re-renders — this is by design.
+- **Strategy**: If you need UI to update when a value changes, use `useState` or `useReducer` instead. Use `useRef` only for values that should NOT trigger re-renders: DOM references, timers, previous value tracking, and imperative handles.
+- **Tool sequence**: file_read (ref usage) → file_edit (convert to useState if re-render is needed)
+- **Pitfall**: Do NOT try to force a re-render after mutating a ref. Switch to state.
+
+## Verification
+- ESLint: `eslint --ext .tsx,.ts src/` — look for `react-hooks/rules-of-hooks` and `react-hooks/exhaustive-deps` violations.
+- Type check: `tsc --noEmit`
+- Dev server: confirm no console errors beginning with `Warning: ` or `Error: ` in the browser.
+
+## Validation Checklist
+- [ ] All hooks called unconditionally at component top level, before any early returns
+- [ ] useEffect dependency arrays include all referenced variables (no exhaustive-deps suppressions)
+- [ ] No inline object or array literals in dependency arrays
+- [ ] All list renders have stable unique keys from data (not array index)
+- [ ] Browser-only code wrapped in useEffect or guarded with `typeof window !== "undefined"`
+- [ ] Context values memoized with useMemo if they are object or array literals
+- [ ] Async data access guarded with null/undefined check at render time

package/dist/skills/skills/languages/ruby.md

@@ -0,0 +1,78 @@
+## Identity
+- domain: ruby
+- type: language
+- confidence: 0.92
+
+# Ruby — Error Pattern Reference
+
+Read the full backtrace before acting. Ruby exceptions include the class, message, and call stack — all three matter.
+
+## Error Code Quick Reference
+- **NoMethodError** — Called a method on nil or wrong object type.
+- **LoadError** — require path not found; gem not installed or path wrong.
+- **ArgumentError** — Wrong number of arguments or invalid argument value.
+- **NameError** — Uninitialized constant; missing require or wrong namespace.
+- **TypeError** — Operation applied to wrong type (e.g., nil coercion).
+- **Encoding::UndefinedConversionError** — Encoding incompatibility during string conversion.
+- **RuntimeError** — Generic raise without a specific exception class.
+- **ZeroDivisionError** — Division by zero.
+- **KeyError** — fetch on a Hash with a missing key and no default.
+- **Errno::ENOENT** — File not found on disk.
+
+## Known Error Patterns
+
+### NoMethodError: undefined method for nil
+- **Symptom**: `NoMethodError: undefined method 'foo' for nil:NilClass`
+- **Cause**: A method is called on a variable that is nil. Common after a failed `find`, `first`, optional chain that returns nil, or a hash lookup with a missing key.
+- **Strategy**: 1. Read the backtrace line to identify the variable. 2. Trace where the variable is assigned — grep the variable name and read assignments. 3. Add a nil guard: `return unless obj`, `obj&.method`, or raise a more descriptive error if nil is illegal at that point.
+- **Tool sequence**: grep (variable assignment) → file_read (surrounding block) → file_edit (add nil guard)
+- **Pitfall**: Do NOT add `.to_s` or similar to silence the error. Determine why nil is reaching that line.
+
+### LoadError: cannot load such file
+- **Symptom**: `LoadError: cannot load such file -- some/path`
+- **Cause**: `require` or `require_relative` path is wrong, the gem is not in the Gemfile, or the gem is not installed.
+- **Strategy**: 1. Check if the path is a gem name — grep Gemfile for the name. 2. If missing, add it with `bundle add <gem>`. 3. If it is a relative path, verify the file exists using shell_exec. 4. Check the load path with `$LOAD_PATH` in a debug session if the gem is installed but not found.
+- **Tool sequence**: grep (Gemfile) → shell_exec (`ls` on path) → file_edit (Gemfile or require statement)
+- **Pitfall**: Do NOT assume the gem is installed. Always check Gemfile.lock for the actual resolved gem list.
+
+### ArgumentError: wrong number of arguments
+- **Symptom**: `ArgumentError: wrong number of arguments (given N, expected M)`
+- **Cause**: Calling a method with more or fewer arguments than defined. Common after refactoring method signatures.
+- **Strategy**: 1. Read the method definition (grep the method name). 2. Count required, optional (`= default`), and splat (`*args`) parameters. 3. Fix the call site to match the signature. If the definition is wrong, update it and check all call sites.
+- **Tool sequence**: grep (method name `def `) → file_read (definition) → grep (call sites) → file_edit
+- **Pitfall**: Do NOT add default values to all parameters just to silence the error — required parameters are required for a reason.
+
+### NameError: uninitialized constant
+- **Symptom**: `NameError: uninitialized constant Foo::Bar`
+- **Cause**: A class or module constant is referenced but not loaded. Missing require, wrong namespace, or autoloading not configured.
+- **Strategy**: 1. Search for the class definition (grep `class Bar` or `module Bar`). 2. Check if the file is required or autoloaded. In Rails, verify the file is in an autoloaded directory. Outside Rails, add `require_relative` or `require`. 3. Check the namespace — `Foo::Bar` means `Bar` must be defined inside `module Foo`.
+- **Tool sequence**: grep (`class Bar\|module Bar`) → file_read (top of failing file) → file_edit (add require or fix namespace)
+- **Pitfall**: Do NOT add a `rescue NameError` to suppress this. Find and load the correct constant.
+
+### Encoding::UndefinedConversionError
+- **Symptom**: `Encoding::UndefinedConversionError: "\xXX" from ASCII-8BIT to UTF-8`
+- **Cause**: A string with one encoding is being converted to an incompatible encoding. Common when reading binary files, external HTTP responses, or database fields without encoding declared.
+- **Strategy**: 1. Identify the source of the problematic string (file read, HTTP body, DB field). 2. Set the correct source encoding: `string.force_encoding('UTF-8')` if you know the source is UTF-8. 3. Use `encode` with error handling: `string.encode('UTF-8', invalid: :replace, undef: :replace)` for lossy conversion if the data may be dirty. 4. For file reads, pass `encoding: 'UTF-8'` to `File.read`.
+- **Tool sequence**: file_read (string source) → file_edit (add encoding declaration or encode call)
+- **Pitfall**: Do NOT use `force_encoding` blindly — it only relabels the encoding without converting. Use `encode` when actual conversion is needed.
+
+### Frozen String Modification
+- **Symptom**: `FrozenError: can't modify frozen String` (or `RuntimeError` in older Ruby)
+- **Cause**: Attempting to mutate a frozen string. Common with `# frozen_string_literal: true` magic comment, string literals from constants, or strings returned from certain gem methods.
+- **Strategy**: 1. Read the line causing the error. 2. If using `<<`, `gsub!`, `sub!`, or direct index assignment, replace with the non-bang version and reassign: `str = str.gsub(...)`. 3. If mutation is intentional, use `str = str.dup` before mutating.
+- **Tool sequence**: file_read (error line) → file_edit (replace mutating call with non-mutating + reassign)
+- **Pitfall**: Do NOT remove the `# frozen_string_literal: true` comment. Fix the mutation instead.
+
+## Verification
+Run: `ruby -c <file>` for syntax check, `bundle exec ruby <file>` for runtime.
+- For Rails: `bundle exec rails runner <file>` or run the test suite.
+- Always run with `bundle exec` to use the Gemfile-resolved gem versions.
+
+## Validation Checklist
+- [ ] No `rescue Exception` without re-raising or explicit justification (catches signals)
+- [ ] All `require` paths verified to exist or gem present in Gemfile
+- [ ] nil guard added wherever a method result could be nil
+- [ ] No `.freeze` removed to fix FrozenError — fix the mutation instead
+- [ ] Encoding specified at string source, not just at the point of failure
+- [ ] `bundle exec` used for all ruby/rake/rails invocations
+- [ ] Method signatures verified at all call sites after any definition change

package/dist/skills/skills/languages/rust.md

@@ -0,0 +1,77 @@
+## Identity
+- domain: rust
+- type: language
+- confidence: 0.95
+
+# Rust — Error Pattern Reference
+
+Read the full `rustc` error output including the `help:` and `note:` lines. Rust's compiler diagnostics are among the most detailed available — the suggestion often contains the exact fix.
+
+## Error Code Quick Reference
+- **E0502** — Cannot borrow as mutable because it is also borrowed as immutable.
+- **E0505** — Cannot move out of value because it is borrowed.
+- **E0507** — Cannot move out of `*x` which is behind a reference.
+- **E0106** — Missing lifetime specifier.
+- **E0277** — Trait bound not satisfied.
+- **E0308** — Mismatched types.
+- **E0004** — Non-exhaustive patterns in match.
+- **E0382** — Use of moved value.
+- **E0499** — Cannot borrow as mutable more than once at a time.
+- **E0716** — Temporary value dropped while borrowed.
+
+## Known Error Patterns
+
+### Pattern: borrow checker — cannot borrow as mutable (E0502 / E0499)
+
+- **symptom**: `cannot borrow 'x' as mutable because it is also borrowed as immutable` or `cannot borrow 'x' as mutable more than once at a time`
+- **cause**: Rust enforces at most one mutable reference OR any number of immutable references at a time. Violating this at the same scope triggers E0502/E0499.
+- **strategy**: 1. Read the error span — it shows exactly where each borrow starts and ends. 2. Restructure code so the immutable borrow is dropped (goes out of scope or is no longer used) before the mutable borrow begins. 3. If both borrows are needed simultaneously, clone the data for the immutable side. 4. For collections, use `split_at_mut` or index-based access instead of simultaneous slice references.
+- **toolSequence**: file_read (error lines) → file_edit (restructure borrow scopes or add `.clone()`)
+- **pitfall**: Do NOT reach for `unsafe` or `RefCell` as the first solution. Restructuring lifetimes or cloning is almost always the correct fix.
+
+### Pattern: lifetime annotation error (E0106 / E0597)
+
+- **symptom**: `missing lifetime specifier` or `borrowed value does not live long enough` — value dropped while still borrowed
+- **cause**: A reference in a struct, function return, or trait object lacks a lifetime annotation, or a local variable is returned as a reference but is dropped at end of function.
+- **strategy**: 1. Read the error to find where the lifetime is needed. 2. For struct fields holding references, add a lifetime parameter to the struct: `struct Foo<'a> { x: &'a str }`. 3. For function returns borrowing from input, add matching lifetime: `fn foo<'a>(x: &'a str) -> &'a str`. 4. If returning a reference to a local, return an owned value (`String`, `Vec`, etc.) instead. 5. Use `'static` only for string literals or `Box::leak` — never to silence the error.
+- **toolSequence**: file_read (struct or function definition) → file_edit (add lifetime parameters)
+- **pitfall**: Do NOT add `'static` to every lifetime just to make the compiler happy — it severely restricts callers and is almost always wrong.
+
+### Pattern: match non-exhaustive (E0004)
+
+- **symptom**: `non-exhaustive patterns: X not covered` in a `match` expression
+- **cause**: The match does not cover all variants of an enum, or a range/literal pattern leaves some values unhandled.
+- **strategy**: 1. Read the error to find the uncovered variant(s). 2. Add an explicit arm for each missing variant. 3. If a catch-all is semantically correct, add `_ => { /* handle default */ }` at the end. 4. For enums you own, prefer explicit arms over `_` so new variants added later cause compile errors.
+- **toolSequence**: file_read (enum definition) → file_read (match expression) → file_edit (add missing arms)
+- **pitfall**: Do NOT add `_ => unreachable!()` unless you have formally proven the branch cannot be reached — prefer `_ => panic!("unexpected variant: {:?}", x)` for better diagnostics.
+
+### Pattern: unwrap on None/Err (runtime panic)
+
+- **symptom**: `thread 'main' panicked at 'called Option::unwrap() on a None value'` or `called Result::unwrap() on an Err value`
+- **cause**: `.unwrap()` or `.expect()` on an `Option` or `Result` that is `None`/`Err` at runtime. Often from file I/O, parsing, or indexing.
+- **strategy**: 1. Locate every `.unwrap()` and `.expect()` in the code path that panicked. 2. Replace with proper error propagation using `?` operator or explicit match. 3. For `Option`, use `.unwrap_or(default)`, `.unwrap_or_else(|| compute())`, or `if let Some(x) = opt { ... }`. 4. For `Result`, propagate with `?` in functions that return `Result`, or handle with `match`/`if let Err(e)`.
+- **toolSequence**: grep (`\.unwrap()\|\.expect(`) → file_read (each occurrence) → file_edit (replace with `?` or match)
+- **pitfall**: Do NOT replace `.unwrap()` with `.unwrap_or_default()` blindly — the default value (empty string, 0, false) may silently cause incorrect behavior downstream.
+
+### Pattern: trait not implemented for type (E0277)
+
+- **symptom**: `the trait bound 'MyType: SomeTrait' is not satisfied` or `'MyType' doesn't implement 'Display'`
+- **cause**: A generic function, operator, or macro requires a trait that the concrete type does not implement. Common cases: `Display`, `Debug`, `Clone`, `Send`, `Sync`, `Iterator`.
+- **strategy**: 1. Read the full error including `note:` lines — they list which trait is required and where. 2. For `Debug`/`Clone`/`PartialEq`, add `#[derive(Debug, Clone, PartialEq)]` to the struct. 3. For custom traits, implement them manually. 4. For `Send`/`Sync`, check if the type contains non-Send/Sync fields (like `Rc`, raw pointers) and replace with thread-safe alternatives (`Arc`). 5. For third-party types, use a newtype wrapper to implement the trait.
+- **toolSequence**: file_read (type definition) → file_edit (add `#[derive(...)]` or `impl Trait for Type`)
+- **pitfall**: Do NOT implement `unsafe impl Send for T` to silence the error — this can cause data races. Fix the underlying non-Send field instead.
+
+## Verification
+Run: `cargo check` and `cargo clippy -- -D warnings`
+- `cargo check` exit 0 = no compile errors (faster than `cargo build`).
+- `cargo clippy` with `-D warnings` = no lints that could become bugs.
+- For tests: `cargo test`
+
+## Validation Checklist
+- [ ] `cargo check` exits 0 with no errors
+- [ ] `cargo clippy -- -D warnings` exits 0
+- [ ] No `.unwrap()` in production code paths without comment explaining the guarantee
+- [ ] Every `context.WithCancel` equivalent (Drop impl) verified to run on all paths
+- [ ] Lifetime annotations are minimal — not `'static` unless truly static
+- [ ] Non-exhaustive match arms handled explicitly, not silently with `_`
+- [ ] `unsafe` blocks, if any, have a `// SAFETY:` comment explaining the invariant

package/dist/skills/skills/languages/solidity.md

@@ -0,0 +1,81 @@
+## Identity
+- domain: solidity
+- type: language
+- confidence: 0.95
+
+# Solidity — Error Pattern Reference
+
+Read the exact compiler error and line number first. Solidity errors often point to a security vulnerability, not just a type mismatch — treat every warning as a potential exploit vector.
+
+## Error Code Quick Reference
+- **SWC-107** — Reentrancy: external call before state update.
+- **SWC-101** — Integer overflow/underflow (pre-0.8.x without SafeMath).
+- **SWC-104** — Unchecked return value from low-level call.
+- **SWC-115** — tx.origin used for authentication.
+- **SWC-128** — DoS with failed call (gas exhaustion).
+- **TypeError: Overriding function missing "override"** — function override not declared.
+- **TypeError: Function state mutability can be restricted** — view/pure missing.
+- **Warning: Return value of low-level call is not used** — unchecked `.call()` return.
+- **DeclarationError: Identifier already declared** — name collision in scope.
+
+## Known Error Patterns
+
+### Reentrancy Attack — Call Before State Update
+- **Symptom**: Funds drained repeatedly in a single transaction; contract balance zeroed unexpectedly. Compiler may emit no error — this is a logic bug.
+- **Cause**: An external `.call{value: amount}()` is made before the internal accounting state (balance mapping, flag) is updated. The callee's `receive()` or `fallback()` re-enters the function before the state reflects the first withdrawal.
+- **Strategy**: 1. Grep all external calls (`\.call{`, `\.transfer(`, `\.send(`). 2. For each call site, read the function and verify the state update (e.g., `balances[msg.sender] -= amount`) happens BEFORE the call. 3. Apply the Checks-Effects-Interactions (CEI) pattern: checks first, state mutations second, external interactions last. 4. As an additional layer, add a `ReentrancyGuard` modifier using a `locked` boolean flag. 5. Re-audit any function that calls an external contract.
+- **Tool sequence**: grep (`\.call{value`) → file_read → file_edit (move state update before call, add nonReentrant modifier)
+- **Pitfall**: Do NOT rely on `transfer()` or `send()` alone as reentrancy protection — their 2300 gas stipend is not guaranteed to remain safe with EVM upgrades (EIP-1884).
+
+### Integer Overflow / Underflow — Pre-0.8.x SafeMath
+- **Symptom**: Token balances wrap around to huge values; subtraction from small value produces near-`uint256` max.
+- **Cause**: Solidity <0.8.0 does not revert on arithmetic overflow/underflow. `uint8(255) + 1 == 0`. Without SafeMath, any unchecked arithmetic can wrap.
+- **Strategy**: 1. Check the `pragma solidity` version at the top of each file. 2. If <0.8.0, grep all arithmetic operations (`+`, `-`, `*`, `/`) on numeric types. 3. Import and use OpenZeppelin's SafeMath library for every operation, or upgrade to >=0.8.0 which has built-in overflow checks. 4. After upgrade, test edge cases (max value +1, 0 -1) in unit tests.
+- **Tool sequence**: grep (`pragma solidity`) → file_read (arithmetic operations) → file_edit (add SafeMath or upgrade pragma)
+- **Pitfall**: Do NOT assume `uint256` is safe from underflow — subtracting from a value smaller than the subtrahend wraps to near `2^256`. Underflow is as dangerous as overflow.
+
+### Unchecked Return Value — ERC20 transfer / low-level call
+- **Symptom**: Transfer silently fails; funds are not moved but execution continues. Non-reverting ERC20 tokens (e.g., USDT) return `false` instead of reverting.
+- **Cause**: `token.transfer(to, amount)` on non-standard ERC20 tokens returns `false` on failure instead of reverting. Low-level `.call()` always returns `(bool success, bytes memory data)` — ignoring `success` means silent failures.
+- **Strategy**: 1. Grep all `.transfer(`, `.transferFrom(`, `.call(` usages. 2. For ERC20 transfers, use OpenZeppelin's `SafeERC20.safeTransfer()` which internally checks return values and reverts on failure. 3. For low-level calls, always destructure and check: `(bool success, ) = addr.call{...}(...); require(success, "call failed");`. 4. Audit all external call return values.
+- **Tool sequence**: grep (`\.call(`, `\.transfer(`) → file_read → file_edit (wrap with SafeERC20 or add require(success))
+- **Pitfall**: Do NOT use `.transfer()` on ERC20 tokens and assume it behaves like ETH transfer — they are completely different methods.
+
+### tx.origin Authentication Bypass
+- **Symptom**: Phishing contract can call victim contract on behalf of the original signer; access control is bypassed.
+- **Cause**: `tx.origin` refers to the original EOA that initiated the entire transaction chain, not the immediate caller. A malicious contract in the call chain can exploit `require(tx.origin == owner)` because `tx.origin` is the user, not the attacker contract.
+- **Strategy**: 1. Grep all occurrences of `tx.origin`. 2. Replace every access control check with `msg.sender` — the immediate caller. 3. Only use `tx.origin` if you explicitly need to differentiate EOA from contract (e.g., `require(tx.origin == msg.sender, "no contracts")`) — but even this is rarely correct.
+- **Tool sequence**: grep (`tx\.origin`) → file_read → file_edit (replace with msg.sender)
+- **Pitfall**: Do NOT use `tx.origin == msg.sender` as a "contracts not allowed" guard in production — wallets like Gnosis Safe are themselves contracts and will be blocked.
+
+### Gas Estimation Failure — Out-of-Gas in Loop
+- **Symptom**: Transaction reverts with `out of gas`; Hardhat/Foundry estimates wildly differ from actual gas. Loops over dynamic arrays cause this.
+- **Cause**: Iterating over an unbounded array (e.g., `for (uint i = 0; i < users.length; i++)`) consumes gas proportional to array size. If the array grows large enough, the gas cost exceeds the block gas limit, permanently locking the function.
+- **Strategy**: 1. Grep all `for` loops and `while` loops in contracts. 2. Identify loops over storage arrays that are user-controlled or unbounded. 3. Replace unbounded loops with a pull-payment pattern (each user claims individually) or pagination (process N items per call). 4. Use events for off-chain aggregation instead of on-chain loops. 5. Set a max iteration constant if the loop must exist.
+- **Tool sequence**: grep (`for (`, `while (`) → file_read → file_edit (add max cap or extract to pull pattern)
+- **Pitfall**: Do NOT add a `gasleft() > MINIMUM` check as the primary fix — it converts a revert into a partial execution, which is often worse.
+
+### Visibility Not Specified — Default Public
+- **Symptom**: Sensitive function callable by anyone; Slither warns "function has no visibility specifier."
+- **Cause**: Solidity <0.5.0 defaulted functions to `public` when no visibility was specified. In >=0.5.0 this is a compile error, but audits of legacy code reveal functions that should be `internal` or `private`.
+- **Strategy**: 1. Grep all `function` declarations. 2. Verify each has an explicit `public`, `external`, `internal`, or `private` specifier. 3. Apply principle of least privilege: prefer `internal` for helper functions, `external` for functions only called from outside. 4. Run Slither static analysis to catch visibility issues automatically.
+- **Tool sequence**: grep (`function `) → file_read → file_edit (add explicit visibility)
+- **Pitfall**: Do NOT blindly mark all functions `private` — internal contract helpers called by child contracts must be `internal`.
+
+## Verification
+Run: `solc --strict-assembly` or `npx hardhat compile`
+- Zero errors and zero warnings (especially SWC warnings) = passing baseline.
+- Run Slither: `slither . --print human-summary` for static analysis.
+- Run Foundry tests: `forge test -vvv` — all tests must pass.
+
+## Validation Checklist
+- [ ] All arithmetic uses SafeMath or pragma >=0.8.0 with no `unchecked` blocks near user input
+- [ ] No `tx.origin` used for access control
+- [ ] Every `.call()` return value is checked with `require(success, ...)`
+- [ ] CEI pattern enforced: state updates happen before all external calls
+- [ ] No unbounded loops over user-controlled storage arrays
+- [ ] All functions have explicit visibility specifiers
+- [ ] Reentrancy guard applied to all state-changing functions that make external calls
+- [ ] ERC20 interactions use SafeERC20 wrappers
+- [ ] Events emitted for all state changes (for off-chain auditability)
+- [ ] Slither static analysis passes with no high-severity findings

package/dist/skills/skills/languages/sql.md

@@ -0,0 +1,74 @@
+## Identity
+- domain: sql
+- type: language
+- confidence: 0.91
+
+# SQL — Error Pattern Reference
+
+Read the query plan (`EXPLAIN ANALYZE`) before optimizing. Most SQL performance bugs are visible in the plan. Always check the execution count and actual rows vs. estimated rows.
+
+## Quick Reference
+- **Seq Scan** — Full table scan; usually means missing or unused index.
+- **Nested Loop** — Can be N+1 if the inner query is driven by outer rows without batching.
+- **Hash Join / Merge Join** — Efficient for large set joins.
+- **Filter** — Rows filtered AFTER scan; ideally filters happen at index scan level.
+- **NULL** — Not equal to anything, including itself. Use `IS NULL` / `IS NOT NULL`.
+
+## Known Error Patterns
+
+### N+1 Query — Missing JOIN
+- **Symptom**: Application issues one query to fetch N parent rows, then N separate queries to fetch child data. Slow page loads proportional to result set size.
+- **Cause**: ORM lazy loading or application-level loop issuing per-row queries. The database work is done outside SQL.
+- **Strategy**: 1. Log all queries during a request (ORM query log or `pg_stat_statements`). 2. Identify repeated queries differing only by an ID parameter. 3. Rewrite as a single query using JOIN or a subquery: `SELECT p.*, c.* FROM parents p JOIN children c ON c.parent_id = p.id WHERE p.id IN (...)`. 4. In ORMs, use eager loading: `.includes()`, `.eager_load()`, `JOIN FETCH`, etc.
+- **Tool sequence**: shell_exec (query log or EXPLAIN) → file_read (ORM query code) → file_edit (add JOIN or eager load)
+- **Pitfall**: Do NOT add `LIMIT 1` to inner queries as a workaround — batch the entire fetch in one query.
+
+### Index Not Used — Function on Indexed Column
+- **Symptom**: `EXPLAIN ANALYZE` shows Seq Scan on a large table even though an index exists on the column in the WHERE clause.
+- **Cause**: Wrapping an indexed column in a function (`WHERE LOWER(email) = ...`, `WHERE DATE(created_at) = ...`) prevents the index from being used because the index stores the raw value, not the function result.
+- **Strategy**: 1. Run `EXPLAIN ANALYZE` on the slow query. 2. Identify the Seq Scan and the WHERE predicate. 3. Options: a) Create a functional index: `CREATE INDEX ON users (LOWER(email));`. b) Rewrite the query to avoid the function on the column side: `WHERE created_at >= '2024-01-01' AND created_at < '2024-01-02'` instead of `WHERE DATE(created_at) = '2024-01-01'`. c) Store the normalized value in a separate indexed column.
+- **Tool sequence**: shell_exec (`EXPLAIN ANALYZE <query>`) → file_read (query definition) → file_edit (rewrite predicate or add functional index)
+- **Pitfall**: Do NOT add an index to the column if the query wraps it in a function. The new index will also be unused.
+
+### NULL Comparison — IS NULL vs = NULL
+- **Symptom**: `WHERE column = NULL` returns zero rows even when null values exist. `WHERE column != NULL` also returns zero rows.
+- **Cause**: In SQL, NULL represents an unknown value. Any comparison with `=`, `!=`, `<`, `>` against NULL evaluates to NULL (unknown), not TRUE or FALSE. Rows are only returned where the predicate is TRUE.
+- **Strategy**: 1. Replace `= NULL` with `IS NULL`. 2. Replace `!= NULL` or `<> NULL` with `IS NOT NULL`. 3. For COALESCE or conditional logic: `COALESCE(column, default_value)`.
+- **Tool sequence**: grep (`= NULL\|!= NULL\|<> NULL`) → file_read → file_edit (replace with IS NULL / IS NOT NULL)
+- **Pitfall**: `NOT IN (subquery)` silently returns zero rows if the subquery contains any NULL values. Use `NOT EXISTS` instead for nullable subqueries.
+
+### Implicit Type Conversion in WHERE
+- **Symptom**: Query returns wrong results or runs slowly because an index is not used. No error is raised.
+- **Cause**: Comparing a column to a literal of a different type forces an implicit cast. E.g., comparing an integer column to a string literal `WHERE id = '123'`, or a varchar column to a number. Some databases cast the column (index unusable); others cast the literal (usually OK).
+- **Strategy**: 1. Identify the column type from the schema. 2. Ensure the literal or bound parameter matches the column type exactly. 3. In application code, use parameterized queries with the correct type binding. 4. Run `EXPLAIN ANALYZE` to confirm the plan does not include a cast on the column side.
+- **Tool sequence**: shell_exec (`\d table_name` or schema query) → file_read (query) → file_edit (cast literal or fix parameter type)
+- **Pitfall**: Do NOT cast the column in the WHERE clause to match the literal: `WHERE CAST(id AS VARCHAR) = '123'` — this prevents index use. Cast the literal instead: `WHERE id = 123`.
+
+### Missing Transaction Rollback on Error
+- **Symptom**: Partial data written to the database when an error occurs mid-operation. Data is in an inconsistent state.
+- **Cause**: Multiple related DML statements (INSERT, UPDATE, DELETE) are not wrapped in a transaction, or the error handling path does not issue a ROLLBACK.
+- **Strategy**: 1. Wrap all related DML in `BEGIN; ... COMMIT;`. 2. In application code, use try/catch with ROLLBACK in the catch block. 3. Use database-level constraints (FK, UNIQUE, CHECK) as the last line of defense. 4. Test the error path explicitly.
+- **Tool sequence**: grep (`INSERT\|UPDATE\|DELETE`) → file_read (transaction boundary) → file_edit (add BEGIN/COMMIT/ROLLBACK)
+- **Pitfall**: Do NOT issue COMMIT before verifying all statements succeeded. Commit only at the outermost transaction boundary.
+
+### Missing Index on Foreign Key
+- **Symptom**: Deletes or updates on parent table are slow; parent-side queries perform Seq Scans on child table.
+- **Cause**: Foreign key columns on the child table are not indexed. The database must scan the entire child table to enforce FK constraints on parent modification.
+- **Strategy**: 1. Identify all FK columns in the schema. 2. For each FK column, check if an index exists: `\d child_table`. 3. Add index: `CREATE INDEX ON child_table (parent_id);`.
+- **Tool sequence**: shell_exec (schema inspection) → file_edit (migration to add index)
+- **Pitfall**: Do NOT add the index to the parent's primary key column — add it to the FK column on the child table.
+
+## Verification
+Run: `EXPLAIN ANALYZE <query>` for any query touching tables with >10k rows.
+- Target: no Seq Scan on large tables (unless the query reads most of the table).
+- Target: actual rows ≈ estimated rows (large divergence indicates stale statistics — run `ANALYZE table_name`).
+
+## Validation Checklist
+- [ ] `EXPLAIN ANALYZE` reviewed for all slow queries (>100ms)
+- [ ] No `= NULL` or `!= NULL` comparisons in WHERE clauses
+- [ ] All function-wrapped column predicates reviewed for index usage
+- [ ] All multi-statement DML wrapped in explicit transactions
+- [ ] FK columns on child tables have indexes
+- [ ] `NOT IN (subquery)` replaced with `NOT EXISTS` where subquery may return NULLs
+- [ ] Parameterized queries used — no string-concatenated SQL
+- [ ] `ANALYZE` run after bulk data changes to refresh statistics

package/dist/skills/skills/languages/svelte.md

@@ -0,0 +1,74 @@
+## Identity
+- domain: svelte
+- type: language
+- confidence: 0.91
+
+# Svelte — Error Pattern Reference
+
+Read the Svelte compiler error in full — it includes the file, line, column, and a description. Runtime errors appear in the browser console; compiler errors appear in the terminal during build.
+
+## Quick Reference
+- **'X' is not defined** — Variable used in template not declared in `<script>`.
+- **'store' is not a store** — Variable used with `$` prefix is not a Svelte store.
+- **Uncaught ReferenceError: X is not defined** — SSR/hydration mismatch or browser-only API used during SSR.
+- **Each block must have a key expression** — Missing `(key)` in `{#each}`.
+- **Cannot read properties of undefined** — Slot prop or store value not yet initialized.
+
+## Known Error Patterns
+
+### Reactive Statement Not Triggering — Mutation vs Reassignment
+- **Symptom**: `$: derivedValue = compute(arr)` does not update when `arr` is mutated (e.g., `arr.push(item)`). UI stays stale.
+- **Cause**: Svelte's reactivity is triggered by assignment. Mutating an array or object in place (`.push`, `.pop`, property assignment without reassignment) does not trigger reactivity because no assignment to the top-level variable occurs.
+- **Strategy**: 1. After any mutation, reassign the variable: `arr.push(item); arr = arr;`. 2. Use immutable patterns: `arr = [...arr, item]` for push, `arr = arr.filter(...)` for remove. 3. For objects: `obj = { ...obj, key: value }` or `obj.key = value; obj = obj;`.
+- **Tool sequence**: grep (mutation calls on reactive variable) → file_read → file_edit (add reassignment after mutation or switch to immutable pattern)
+- **Pitfall**: Do NOT mutate a prop from inside a child component. Props flow down; use an event or a writable store for two-way data flow.
+
+### Store Subscription Not Unsubscribed
+- **Symptom**: Memory leak or stale callbacks after component is destroyed. Effects fire on unmounted components. Warning: "Cannot update a component after it has been destroyed."
+- **Cause**: Manual store subscription using `store.subscribe(callback)` returns an unsubscribe function. If not called in `onDestroy`, the callback keeps firing after the component is unmounted.
+- **Strategy**: 1. For manual subscriptions, always unsubscribe in `onDestroy`: `const unsub = store.subscribe(cb); onDestroy(unsub);`. 2. Use the `$store` auto-subscription syntax instead — Svelte automatically unsubscribes when the component is destroyed: `$myStore` in the template or reactive block.
+- **Tool sequence**: grep (`\.subscribe\(`) → file_read (onDestroy presence) → file_edit (add onDestroy(unsub) or replace with $ syntax)
+- **Pitfall**: Do NOT call `unsub()` in `onMount` return — that unsubscribes too early. Call it in `onDestroy`.
+
+### Slot Prop Undefined
+- **Symptom**: `Cannot read properties of undefined (reading 'x')` when accessing a slot prop. The slot renders but prop values are undefined.
+- **Cause**: The parent passes a slot without the expected `let:propName` binding, or the child component's `<slot>` element does not pass the prop correctly with the named attribute.
+- **Strategy**: 1. In the child component, verify the slot exports the prop: `<slot propName={value} />`. 2. In the parent, bind the prop with `let:propName`: `<svelte:fragment slot="name" let:propName>`. 3. Check for typos in the prop name — they must match exactly.
+- **Tool sequence**: file_read (child component slot definition) → file_read (parent usage) → file_edit (add or fix let: binding)
+- **Pitfall**: Slot props are only available within the slot markup in the parent. Do NOT try to use them outside the `<svelte:fragment>` or slot element.
+
+### SSR Hydration Mismatch
+- **Symptom**: Console warning: `Hydration mismatch` or elements flicker/reset on initial page load. Content rendered server-side differs from client-side initial render.
+- **Cause**: Code that runs differently on server vs client: `Math.random()`, `Date.now()`, `window`/`document` access, locale-dependent formatting, or data fetched at different times.
+- **Strategy**: 1. Identify the non-deterministic or browser-only value. 2. For browser-only APIs, guard with `if (browser)` from `$app/environment`, or use `onMount` (which only runs on client). 3. For random/time values, generate them on the server and pass as props, or synchronize the seed. 4. For locale: use a consistent locale setting shared between server and client.
+- **Tool sequence**: file_read (component that flickers) → grep (`window\|document\|Math.random\|Date.now`) → file_edit (move to onMount or add browser guard)
+- **Pitfall**: Do NOT wrap entire components with `{#if browser}` as a shortcut — this suppresses SSR entirely and loses SEO benefits. Fix the specific non-deterministic expression.
+
+### Each Block Key Missing
+- **Symptom**: `[svelte] warning: Each block requires a (key) expression` — list items re-render incorrectly, animations are wrong, component state is misattributed when list changes.
+- **Cause**: `{#each items as item}` without `(item.id)` makes Svelte use positional diffing. Reordering, adding, or removing items confuses component identity.
+- **Strategy**: 1. Add a unique key: `{#each items as item (item.id)}`. 2. The key must be a primitive (string, number) or something serializable. 3. Do NOT use array index as a key when items can be reordered or deleted.
+- **Tool sequence**: grep (`{#each`) → file_read (template) → file_edit (add key expression)
+- **Pitfall**: The key goes in parentheses after the item variable: `(item.id)`. Do NOT use `:key` (that is Vue syntax).
+
+### Reactive Declaration Ordering
+- **Symptom**: `$: b = a * 2` uses `a` which is defined by another reactive statement `$: a = fetch(...)`. `b` always sees the previous value of `a`.
+- **Cause**: Svelte orders reactive statements topologically based on declared dependencies. If the dependency graph is not clear (e.g., both depend on the same store side-effect), ordering can be non-intuitive.
+- **Strategy**: 1. Ensure reactive statements form a clear dependency graph. 2. If `b` depends on `a`, write `$: b = a * 2` AFTER `$: a = compute()` in the file, and make the dependency explicit (read `a` in the expression for `b`). 3. For complex derived state, use a store with a derived: `const b = derived(aStore, $a => $a * 2)`.
+- **Tool sequence**: file_read (reactive block order) → file_edit (reorder or extract to derived store)
+- **Pitfall**: Do NOT rely on file-order alone when reactive statements have side effects. Explicit data dependencies are more reliable.
+
+## Verification
+Run: `svelte-check` for static type and template checking (with TypeScript).
+- `vite build` or `svelte-kit build` for full compilation.
+- Browser console must show zero Svelte hydration warnings on initial load.
+
+## Validation Checklist
+- [ ] All array/object mutations followed by reassignment (`arr = arr`) or use immutable update patterns
+- [ ] All `store.subscribe()` calls have matching `onDestroy(unsub)` or replaced with `$store` syntax
+- [ ] All `{#each}` blocks have a `(key)` expression using stable unique ID
+- [ ] Browser-only APIs guarded with `if (browser)` or moved to `onMount`
+- [ ] Slot props bound with `let:propName` in parent matching child's slot attribute
+- [ ] `svelte-check` reports zero errors
+- [ ] Reactive declaration order reflects data dependency order
+- [ ] No component mutations to received props (use events or writable stores)