@yuaone/core 0.8.4 → 0.9.0

package/dist/skills/skills/languages/haskell.md

@@ -0,0 +1,80 @@
+## Identity
+- domain: haskell
+- type: language
+- confidence: 0.88
+
+# Haskell — Error Pattern Reference
+
+Read the full GHC error including source location, the constraint context, and the inferred vs expected types. Haskell errors often appear far from the actual source of the type mismatch — read the constraint trail.
+
+## Error Code Quick Reference
+- **"No instance for (Typeclass x)"** — Missing typeclass instance for a type.
+- **"Couldn't match expected type"** — Type mismatch; read both types carefully.
+- **"Ambiguous type variable"** — GHC cannot determine which instance to use; add type annotation.
+- **"Non-exhaustive patterns"** — Case expression or function definition missing a branch.
+- **"Variable not in scope"** — Name not imported or not in scope; check module imports.
+- **"Couldn't match type 'IO a' with 'a'"** — Forgetting to bind (>>=) or `<-` in do notation.
+- **"Occurs check: cannot construct the infinite type"** — Recursive type without newtype wrapper.
+- **"Module 'X' does not export 'y'"** — Trying to import a name that is not exported.
+
+## Known Error Patterns
+
+### No Instance For — Missing Typeclass
+- **Symptom**: `No instance for (Show MyType) arising from a use of 'print'`; GHC refuses to compile even though the logic seems correct.
+- **Cause**: A typeclass method is used on a type that has not derived or implemented the required instance. Common cases: `Show` needed for printing, `Eq` needed for `==`, `Ord` needed for sorting, `FromJSON`/`ToJSON` needed for Aeson.
+- **Strategy**: 1. Read the error — it says exactly which typeclass is missing for which type. 2. If the type is yours, add a deriving clause: `data MyType = ... deriving (Show, Eq, Ord)`. 3. For more complex instances (e.g., `FromJSON` for a custom type), write the instance manually or use Template Haskell: `$(deriveJSON defaultOptions ''MyType)`. 4. For orphan instances (instance for a type you don't own in a module you don't own), create a `newtype` wrapper. 5. Check that the required module is imported: `import Data.Aeson (FromJSON, ToJSON)`.
+- **Tool sequence**: file_read (type definition) → file_edit (add deriving clause or manual instance) → shell_exec (`cabal build` or `stack build`)
+- **Pitfall**: Do NOT add a `newtype` wrapper just to avoid an orphan instance warning if you can define the instance in the same module as the type — orphan instances cause import order dependencies.
+
+### Space Leak — Lazy Evaluation Accumulation
+- **Symptom**: Memory usage grows linearly with input size for operations that should be constant space (e.g., `foldl sum`); program eventually runs out of memory on large inputs.
+- **Cause**: Haskell is lazy by default — thunks accumulate without being evaluated. `foldl (+) 0 [1..1000000]` builds a chain of a million unevaluated additions before computing anything. The result is held as a thunk until forced.
+- **Strategy**: 1. Replace `foldl` with `foldl'` (strict left fold) from `Data.List`: `import Data.List (foldl')`. 2. Use `BangPatterns` or `$!` for strict accumulation: `go !acc (x:xs) = go (acc + x) xs`. 3. Use `seq` to force evaluation: `let !x = expensiveComputation`. 4. Profile with `+RTS -hc -p` to identify which thunks are accumulating. 5. Consider using strict data structures (`Data.Map.Strict` instead of `Data.Map.Lazy`).
+- **Tool sequence**: grep (`foldl `, `Data.Map` without `.Strict`) → file_read → file_edit (replace with strict versions)
+- **Pitfall**: Do NOT add `seq` or `!` everywhere blindly — forcing evaluation in the wrong place can change semantics for infinite lists and lazy I/O.
+
+### Non-Exhaustive Patterns — Missing Case Branch
+- **Symptom**: `Non-exhaustive patterns in function foo` at runtime; `ghc -W` warns `Pattern match(es) are non-exhaustive`; program crashes on an input that wasn't tested.
+- **Cause**: A `case` expression or multi-equation function definition does not cover all possible inputs. Common cases: not handling `Nothing` in a `Maybe`, missing constructors in a sum type `case`, not handling the empty list `[]`.
+- **Strategy**: 1. Enable `-Wincomplete-patterns` in GHC options (or use `-Wall`). 2. Read which patterns are missing from the warning. 3. Add the missing cases — do not use a wildcard `_ -> error "impossible"` unless you can prove it is truly unreachable. 4. For `Maybe`, always handle both `Just x` and `Nothing`. 5. For sum types you own, add a constructor and let GHC's exhaustiveness checker find all unhandled cases.
+- **Tool sequence**: shell_exec (`ghc -Wall -fno-code MyFile.hs`) → file_read (function with non-exhaustive patterns) → file_edit (add missing case branches)
+- **Pitfall**: Do NOT use `_ -> undefined` or `_ -> error "unreachable"` in case expressions — if the case is truly exhaustive, GHC will tell you; if it is not, `error` crashes the program.
+
+### Ambiguous Type Variable — Missing Annotation
+- **Symptom**: `Ambiguous type variable 'a0' arising from a use of 'show'`; GHC knows a typeclass constraint is needed but cannot choose which instance to use without more information.
+- **Cause**: An expression has a polymorphic type and the context does not constrain it sufficiently. Common cases: `show (read "123")` — GHC doesn't know which type to read into; `mempty` when the monoid type is unclear; numeric literals without context.
+- **Strategy**: 1. Add a type annotation at the ambiguous expression: `show (read "123" :: Int)`. 2. Add a type signature to the function containing the ambiguous expression. 3. Use `ScopedTypeVariables` extension to annotate inner expressions. 4. For `defaulting` issues with numeric types, GHC may default to `Integer` — add explicit `:: Double` or `:: Int` annotations.
+- **Tool sequence**: file_read (ambiguous expression location) → file_edit (add :: TypeAnnotation at the expression or full function signature)
+- **Pitfall**: Do NOT use `asTypeOf` to hint types unless you understand its semantics — add an explicit type annotation instead, which documents intent clearly.
+
+### Import Conflict — Module.Function vs Unqualified
+- **Symptom**: `Ambiguous occurrence 'lookup'` — the name is defined in multiple imported modules; compilation fails.
+- **Cause**: Multiple modules export the same name (e.g., `lookup` from `Prelude` and `Data.Map`, `fromList` from `Data.Set` and `Data.Map`). Both are in scope unqualified.
+- **Strategy**: 1. Use qualified imports for container modules: `import qualified Data.Map.Strict as Map`, `import qualified Data.Set as Set`. 2. Then use `Map.lookup`, `Set.fromList` to disambiguate. 3. Alternatively, use explicit import lists to import only what's needed: `import Data.Map (Map, fromList)`. 4. Hide Prelude clashes: `import Prelude hiding (lookup)`. 5. Enable `PackageImports` extension if the same module name exists in multiple packages.
+- **Tool sequence**: grep (`^import `) → file_read → file_edit (add qualified imports or explicit import lists)
+- **Pitfall**: Do NOT hide Prelude names without a good reason — other readers of the code expect Prelude names to be available and unqualified.
+
+### IO vs Pure Confusion — Missing Bind in do Notation
+- **Symptom**: `Couldn't match type 'IO String' with 'String'`; `Couldn't match expected type '[Char]' with actual type 'IO [Char]'`.
+- **Cause**: In do notation, `let x = getLine` binds the IO action itself (not the result) to `x`. To extract the value from an IO action, use `<-`: `x <- getLine`. Forgetting `<-` leaves the monadic wrapper.
+- **Strategy**: 1. Read the do block carefully — every `IO a` value that needs the inner `a` must use `<-`. 2. `let x = pureExpression` for pure values; `x <- ioAction` for IO actions. 3. For `Maybe`/`Either` in `ExceptT` stacks, use `lift` or `liftIO` to bring IO actions into the monad transformer context. 4. If you need to use a pure value inside IO, it is already usable — no wrapping needed.
+- **Tool sequence**: file_read (do block with type error) → file_edit (change `let x =` to `x <-` for IO actions)
+- **Pitfall**: Do NOT use `unsafePerformIO` to force IO values into pure context — this breaks referential transparency and causes non-deterministic behavior.
+
+## Verification
+Run: `cabal build 2>&1` or `stack build 2>&1`
+- Zero errors, zero warnings with `-Wall -Wincomplete-patterns`.
+- Run HLint: `hlint src/` — apply all "Suggestion" level hints.
+- Run tests: `cabal test` or `stack test`.
+
+## Validation Checklist
+- [ ] GHC build passes with `-Wall` and zero warnings
+- [ ] All `case` expressions and function equations are exhaustive
+- [ ] `foldl` replaced with `foldl'` in all non-lazy contexts
+- [ ] All container module imports are qualified (`Data.Map` as `Map`, etc.)
+- [ ] All ambiguous type variables have explicit annotations
+- [ ] No `error` or `undefined` in production code paths
+- [ ] `Maybe` and `Either` error cases handled (no partial functions like `head` on empty list)
+- [ ] `unsafePerformIO` and `unsafeCoerce` not used
+- [ ] HLint passes with no errors
+- [ ] All exported functions have type signatures

package/dist/skills/skills/languages/java.md

@@ -0,0 +1,77 @@
+## Identity
+- domain: java
+- type: language
+- confidence: 0.95
+
+# Java — Error Pattern Reference
+
+Read the full stack trace including the cause chain (`Caused by:`). Java exceptions cascade — the root cause is at the bottom, not the top.
+
+## Error Code Quick Reference
+- **NullPointerException** — Accessing method/field on a null reference.
+- **ClassCastException** — Casting an object to an incompatible type.
+- **ConcurrentModificationException** — Modifying a collection while iterating it.
+- **OutOfMemoryError: Java heap space** — Heap exhausted. Check for memory leaks.
+- **StackOverflowError** — Unbounded recursion or circular call chain.
+- **ClassNotFoundException** — Class not on classpath at runtime.
+- **NoSuchMethodError** — Compiled against different version than runtime JAR.
+- **IllegalArgumentException** — Invalid argument passed to method.
+- **IllegalStateException** — Method called at wrong lifecycle phase.
+- **checked exception not handled** — Compile error: checked exception must be caught or declared.
+
+## Known Error Patterns
+
+### Pattern: NullPointerException
+
+- **symptom**: `java.lang.NullPointerException` at a specific stack frame, optionally with JDK 14+ helpful NPE message: `Cannot invoke "String.length()" because "str" is null`
+- **cause**: A variable holds `null` when a method call or field access is performed. Common sources: uninitialized fields, method returning null, optional result not checked, collection `get()` returning null for missing key.
+- **strategy**: 1. Read the stack trace to find the exact line. 2. Identify which variable is null at that line. 3. Trace backwards to where it was assigned. 4. Add a null check (`if (x != null)`) or use `Optional<T>` and `.orElse()`/`.orElseThrow()`. 5. For Java 8+, prefer `Objects.requireNonNull(x, "x must not be null")` at entry points. 6. Use `@NonNull` / `@Nullable` annotations for documentation.
+- **toolSequence**: file_read (stack trace line) → grep (variable assignment) → file_edit (add null check or Optional)
+- **pitfall**: Do NOT add null checks everywhere defensively without understanding why null is reached — find the source and fix it there.
+
+### Pattern: ClassCastException
+
+- **symptom**: `java.lang.ClassCastException: class Foo cannot be cast to class Bar`
+- **cause**: An object of type `Foo` was stored in a reference of type `Object` (or a supertype) and then cast to `Bar`, but the actual runtime type is incompatible. Common in legacy collections (pre-generics), deserialization, or downcasting without `instanceof` check.
+- **strategy**: 1. Read the exact class names in the exception. 2. Find where the cast is performed. 3. Add an `instanceof` check before the cast: `if (obj instanceof Bar) { Bar b = (Bar) obj; }`. 4. For Java 16+, use pattern matching: `if (obj instanceof Bar b) { ... }`. 5. If the cast is in serialization/deserialization code, verify the serialized type matches the expected type.
+- **toolSequence**: file_read (cast line) → grep (where the object was originally stored) → file_edit (add instanceof check)
+- **pitfall**: Do NOT suppress with a try/catch around the cast — understand why the wrong type is being stored and fix the storage point.
+
+### Pattern: ConcurrentModificationException
+
+- **symptom**: `java.util.ConcurrentModificationException` while iterating a List, Map, or Set
+- **cause**: The collection was structurally modified (add/remove) while an iterator or enhanced for-loop is active over it. The fail-fast iterator detects the modification counter change and throws.
+- **strategy**: 1. Find the iteration loop. 2. Find the modification inside or outside the loop. 3. Solutions by case: (a) Removing during iteration: use `Iterator.remove()` explicitly. (b) Adding during iteration: collect items to add in a separate list, add them after the loop. (c) Concurrent modification from another thread: use `CopyOnWriteArrayList`, `ConcurrentHashMap`, or synchronize access. 4. For Java streams, collect results to a new list instead of modifying the source.
+- **toolSequence**: file_read (iteration loop) → file_edit (replace with Iterator.remove() or copy-then-modify pattern)
+- **pitfall**: Do NOT switch to `CopyOnWriteArrayList` for single-threaded code — it has high write cost. Use Iterator.remove() for sequential removal.
+
+### Pattern: OutOfMemoryError (heap space)
+
+- **symptom**: `java.lang.OutOfMemoryError: Java heap space` — JVM terminates or GC overhead limit exceeded
+- **cause**: Heap is exhausted. Root causes: (a) unbounded collection growth (cache without eviction), (b) large data loaded entirely into memory, (c) object retention via static fields or listener/callback leaks, (d) insufficient -Xmx setting for workload.
+- **strategy**: 1. Take a heap dump: `-XX:+HeapDumpOnOutOfMemoryError`. 2. Analyze with VisualVM or Eclipse MAT — find the largest retained object. 3. If it is a collection, check the code that populates it — add size bounds or eviction (LRU cache). 4. If it is caused by large data, use streaming (BufferedReader, InputStream) instead of loading entirely. 5. If it is a listener leak, ensure listeners are removed in teardown/close methods. 6. As a last resort, increase `-Xmx` in JVM args, but fix the leak first.
+- **toolSequence**: grep (`new ArrayList\|new HashMap\|static.*List\|static.*Map`) → file_read (population logic) → file_edit (add size limit or streaming)
+- **pitfall**: Do NOT increase -Xmx without investigating the root cause — it only delays the crash and masks the leak.
+
+### Pattern: checked exception not handled
+
+- **symptom**: Compile error: `unreported exception IOException; must be caught or declared to be thrown`
+- **cause**: A method that throws a checked exception is called without either (a) surrounding it in a try-catch or (b) declaring the exception in the calling method's `throws` clause.
+- **strategy**: 1. Read which exception is unhandled and which line throws it. 2. Decide the correct response: (a) Handle it locally — wrap in try-catch and either recover or log + rethrow as unchecked. (b) Propagate it — add `throws IOException` (or the specific exception) to the calling method signature. 3. Avoid catching `Exception` broadly — catch the specific checked exception. 4. When rethrowing as unchecked, use `throw new RuntimeException("context message", e)` to preserve the cause.
+- **toolSequence**: file_read (throwing method signature) → file_edit (add try-catch or throws declaration)
+- **pitfall**: Do NOT use `catch (Exception e) { /* ignore */ }` — swallowed exceptions cause silent failures that are very hard to debug later.
+
+## Verification
+Run: `mvn compile` or `./gradlew compileJava`
+- Exit 0 = no compile errors.
+- For tests: `mvn test` or `./gradlew test`
+- For static analysis: SpotBugs or `./gradlew spotbugsMain`
+
+## Validation Checklist
+- [ ] Compilation succeeds with zero errors
+- [ ] No raw `catch (Exception e) {}` blocks swallowing exceptions silently
+- [ ] All `null` return paths documented and null checks added at consumers
+- [ ] Collections modified during iteration use Iterator.remove() or copy pattern
+- [ ] Checked exceptions either handled locally with recovery or propagated with context
+- [ ] No `instanceof` followed by unchecked cast — use pattern matching (Java 16+)
+- [ ] Static collections have bounded size or explicit eviction policy

package/dist/skills/skills/languages/javascript.md

@@ -0,0 +1,73 @@
+## Identity
+- domain: javascript
+- type: language
+- confidence: 0.90
+
+# JavaScript — Error Pattern Reference
+
+Read the full error message including the call stack. JavaScript errors are often discovered at runtime — the stack trace tells you the exact call chain. Enable strict mode and ESLint to catch many issues earlier.
+
+## Error Code Quick Reference
+- **TypeError: X is not a function** — Value is not callable (undefined/null/wrong type).
+- **TypeError: Cannot read properties of undefined (reading 'x')** — Property access on undefined.
+- **ReferenceError: X is not defined** — Variable not declared or not in scope.
+- **SyntaxError: Cannot use import statement outside a module** — CommonJS vs ESM conflict.
+- **UnhandledPromiseRejection** — Awaited promise rejected without catch.
+- **RangeError: Maximum call stack size exceeded** — Infinite recursion.
+- **TypeError: Assignment to constant variable** — Reassigning const.
+
+## Known Error Patterns
+
+### Pattern: undefined is not a function (this binding)
+
+- **symptom**: `TypeError: this.myMethod is not a function` or `TypeError: undefined is not a function` inside a callback or event handler — `this` is not what was expected
+- **cause**: When a method is passed as a callback, `this` is rebound to the caller's context (often `undefined` in strict mode, or the global object). Common in event listeners, setTimeout callbacks, array methods, and React class component methods.
+- **strategy**: 1. Find where the method is passed as a callback — look for `addEventListener(event, obj.method)` or `arr.forEach(obj.method)`. 2. Bind `this` explicitly: `obj.method.bind(obj)`, or use an arrow function wrapper: `() => obj.method()`. 3. For class methods, use class field arrow functions: `myMethod = () => { ... }` (they bind `this` lexically). 4. For all new code, prefer arrow functions over regular functions in callbacks — arrow functions do not have their own `this`.
+- **toolSequence**: grep (method name passed as callback) → file_read (method definition) → file_edit (add `.bind(this)` or convert to arrow function)
+- **pitfall**: Do NOT use `.bind()` inside render loops or hot paths — it creates a new function reference on every call, causing unnecessary re-renders and GC pressure.
+
+### Pattern: Promise not awaited (floating promise)
+
+- **symptom**: `UnhandledPromiseRejection: ...` in Node.js, or async errors silently disappearing. A function is called that returns a Promise but the result is not awaited or `.catch()`-ed.
+- **cause**: Calling an async function without `await` or `.then()/.catch()` creates a "floating promise" — it runs independently. If it rejects, the rejection is unhandled and either crashes the process (Node.js 15+) or silently disappears (older Node/browser).
+- **strategy**: 1. Enable the `@typescript-eslint/no-floating-promises` or `no-promise-executor-return` ESLint rule to catch these statically. 2. Find async function calls that are not awaited: grep for function calls whose return type is `Promise`. 3. Add `await` at the call site if you need the result or want errors to propagate. 4. If truly fire-and-forget, add explicit error handling: `myAsync().catch(err => console.error(err))`. 5. In Node.js, register `process.on('unhandledRejection', ...)` to log unhandled rejections during development.
+- **toolSequence**: grep (async function calls without await) → file_read → file_edit (add `await` or `.catch()`)
+- **pitfall**: Do NOT add `void myAsync()` to silence the ESLint rule without adding error handling — errors will still be silently lost.
+
+### Pattern: module resolution error (CommonJS vs ESM)
+
+- **symptom**: `SyntaxError: Cannot use import statement outside a module` or `Error: require() of ES Module` or `ReferenceError: exports is not defined`
+- **cause**: Mixing CommonJS (`require`/`module.exports`) and ESM (`import`/`export`) module systems in the same project or across package boundaries. Node.js treats `.js` files as CJS by default unless `"type": "module"` is set in `package.json`, or the file uses the `.mjs`/`.cjs` extension.
+- **strategy**: 1. Read the error — it tells you which file is the problem. 2. Check `package.json` for `"type": "module"` or absence. 3. If the project is CJS, change `import/export` to `require/module.exports`. 4. If the project is ESM, change `require` to `import` and ensure all imports include file extensions (`.js`). 5. For files that must be CJS in an ESM project, rename to `.cjs`. 6. For Node.js scripts importing ESM packages, either switch the script to ESM or use dynamic `import()`.
+- **toolSequence**: file_read (package.json "type" field) → file_read (error file) → file_edit (unify module syntax)
+- **pitfall**: Do NOT mix `require` and `import` in the same file — choose one module system and be consistent. Some bundlers allow it but Node.js runtime does not.
+
+### Pattern: closure in loop (var vs let)
+
+- **symptom**: A loop creates functions (callbacks, event handlers, Promises) that all reference the same final value of the loop variable instead of each iteration's value. Classic: all closures log the same number (e.g., the loop limit).
+- **cause**: `var` is function-scoped, not block-scoped. Inside a `for (var i = 0; ...)` loop, all closures share the same `i` variable — by the time the callback runs, `i` has already reached its final value. `let` creates a new binding per iteration.
+- **strategy**: 1. Find `for (var ...` loops where closures are created inside. 2. Change `var` to `let` — this is the definitive fix for modern JavaScript. 3. For pre-ES6 compatibility, use an IIFE to capture the value: `(function(captured_i) { ... })(i)`. 4. Enable `no-var` ESLint rule to prevent `var` usage entirely.
+- **toolSequence**: grep (`for (var `) → file_read (loop body for closures) → file_edit (change `var` to `let`)
+- **pitfall**: Do NOT convert `var` to `const` in loop initializers — loop variables must be mutable. Use `let`.
+
+### Pattern: prototype chain mutation
+
+- **symptom**: Adding a property to a built-in prototype (`Array.prototype.myMethod`, `Object.prototype.helper`) causes unexpected properties to appear in `for...in` loops, third-party code breaks, or global behavior changes across the codebase.
+- **cause**: Mutating built-in prototypes adds properties to all instances of that type globally. This pollutes every `for...in` loop that does not use `hasOwnProperty`, conflicts with future JavaScript built-ins of the same name, and breaks libraries that rely on prototype purity.
+- **strategy**: 1. Grep for assignments to `*.prototype.*` on built-in types. 2. Replace with utility functions: instead of `Array.prototype.last = fn`, use a standalone `function last(arr) {}` or a module-level helper. 3. For polyfills, check if the property already exists before adding: `if (!Array.prototype.at) Array.prototype.at = ...`. 4. Use ES6+ class inheritance instead of prototype mutation for custom behavior. 5. Enable ESLint `no-extend-native` rule.
+- **toolSequence**: grep (`prototype\.`) → file_read (each mutation) → file_edit (extract to utility function)
+- **pitfall**: Do NOT add `hasOwnProperty` checks everywhere as a workaround — remove the prototype mutation at the source.
+
+## Verification
+Run: `node --check <file>` (syntax check) or `eslint <file>`
+- For projects: `npx eslint src/` or `pnpm run lint`
+- For Node.js module issues: `node -e "require('./file.js')"` or `node --input-type=module`
+
+## Validation Checklist
+- [ ] No `var` in loops that create closures — use `let`
+- [ ] All async function calls either awaited or have `.catch()` error handling
+- [ ] Module system is consistent (all CJS or all ESM) — no mixing
+- [ ] No prototype mutation of built-in types
+- [ ] Callbacks that reference `this` use arrow functions or explicit `.bind()`
+- [ ] `eslint` passes with no errors
+- [ ] No `UnhandledPromiseRejection` in Node.js output

package/dist/skills/skills/languages/kotlin.md

@@ -0,0 +1,75 @@
+## Identity
+- domain: kotlin
+- type: language
+- confidence: 0.95
+
+# Kotlin — Error Pattern Reference
+
+Read the full compiler error or runtime stack trace. Kotlin's type system catches many Java pitfalls at compile time — if an error reaches runtime, trace the `!!` operators and Java interop boundaries first.
+
+## Error Code Quick Reference
+- **Smart cast to 'T' is impossible** — mutable var cannot be smart cast.
+- **Only safe (?.) or non-null asserted (!!.) calls are allowed** — nullable type used directly.
+- **KotlinNullPointerException** — `!!` forced non-null on a null value.
+- **Type mismatch: inferred type is X but Y was expected** — type inference conflict.
+- **'when' expression must be exhaustive** — sealed class/enum not fully covered.
+- **Suspension functions can be called only within coroutine body** — suspend call outside coroutine.
+- **JobCancellationException** — coroutine scope cancelled before completion.
+- **IllegalStateException: Fragment already added** — Fragment lifecycle misuse.
+
+## Known Error Patterns
+
+### Pattern: Smart cast impossible (mutable var)
+
+- **symptom**: `Smart cast to 'Foo' is impossible, because 'x' is a mutable local variable that could have been changed since the null check`
+- **cause**: Kotlin's smart cast requires that the variable cannot change between the null check and its use. A `var` (mutable variable) can be reassigned by another thread or within a lambda, so the compiler refuses to smart cast it.
+- **strategy**: 1. Read the variable declaration — change `var` to `val` if the variable does not need to be reassigned. 2. If `var` is required, capture the current value in a local `val`: `val current = x; if (current != null) { use(current) }`. 3. For class properties, use a local copy: `val prop = this.nullableProp ?: return`. 4. Use the Elvis operator for early returns: `val safe = nullable ?: return`.
+- **toolSequence**: file_read (null check and usage) → file_edit (change `var` to `val` or capture in local val)
+- **pitfall**: Do NOT add `!!` to suppress the error — it converts a compile-time safety check into a runtime crash.
+
+### Pattern: NPE from Java interop (!! operator overuse)
+
+- **symptom**: `kotlin.KotlinNullPointerException` at a line containing `!!`, or `NullPointerException` from a Java method call whose return type is platform type (`String!`)
+- **cause**: Java methods return platform types (e.g., `String!`) which Kotlin treats as non-null by default. The `!!` operator forces non-null and crashes if the value is actually null. Also common when using Java APIs that return null for missing values.
+- **strategy**: 1. Grep for every `!!` in the file. 2. For each `!!`, determine if null is actually possible at runtime. 3. Replace `!!` with safe alternatives: `?: throw IllegalStateException("expected non-null")`, `?: return`, or `?.let { }`. 4. For Java interop returns, use `?: error("descriptive message")` to fail with context. 5. Add `@Nullable` / `@NonNull` annotations to Java methods to improve Kotlin inference.
+- **toolSequence**: grep (`!!`) → file_read (each occurrence) → file_edit (replace with Elvis or safe call)
+- **pitfall**: Do NOT remove `!!` and replace with `?: null` — if the null case is logically impossible, use `?: error("message")` to make violations visible.
+
+### Pattern: coroutine scope leak
+
+- **symptom**: Coroutines continue running after their associated ViewModel/Fragment/Activity is destroyed. Memory grows; callbacks fire on destroyed views. `viewModelScope` or `lifecycleScope` not used properly.
+- **cause**: Using `GlobalScope.launch` or creating a custom `CoroutineScope` without cancelling it in `onCleared()` / `onDestroy()`. The coroutine outlives the owner.
+- **strategy**: 1. Grep for `GlobalScope.launch` and `CoroutineScope(` in the file. 2. Replace `GlobalScope.launch` with `viewModelScope.launch` in ViewModels or `lifecycleScope.launch` in Fragments/Activities. 3. For custom scopes, store the scope in a property and cancel it in the appropriate lifecycle method: `scope.cancel()` in `onCleared()`. 4. For long-running background work, use a `SupervisorJob` + explicit cancellation. 5. Use `viewModelScope` in all ViewModel coroutines — it auto-cancels on `onCleared()`.
+- **toolSequence**: grep (`GlobalScope\|CoroutineScope(`) → file_read → file_edit (replace with viewModelScope/lifecycleScope)
+- **pitfall**: Do NOT use `runBlocking` in production Android code on the main thread — it blocks the UI thread and causes ANRs.
+
+### Pattern: sealed class exhaustiveness warning
+
+- **symptom**: `'when' expression must be exhaustive, add necessary 'is SomeSubclass' branch or 'else' branch instead` — compile error when used as expression; silent miss when used as statement.
+- **cause**: A `when` over a sealed class/interface is missing one or more subclass branches. As a statement, Kotlin allows this (no compile error), but new subclasses added to the sealed class will silently miss handling. As an expression, it is a compile error.
+- **strategy**: 1. Read the sealed class definition to list all subclasses. 2. Add a branch for each missing subclass. 3. To enforce exhaustiveness on `when` statements (not just expressions), use a helper: define an extension property `val <T> T.exhaustive: T get() = this` and call `when (x) { ... }.exhaustive`. 4. Prefer not using `else` in sealed class when expressions — adding a new subclass should cause a compile error, not silently fall through.
+- **toolSequence**: grep (sealed class name) → file_read (all subclasses) → file_read (when expression) → file_edit (add missing branches)
+- **pitfall**: Do NOT add `else -> {}` to silence exhaustiveness — it defeats the purpose of sealed classes as a compile-time completeness guarantee.
+
+### Pattern: data class copy pitfall
+
+- **symptom**: Modifying a `data class` instance via `.copy()` but the original is still referenced elsewhere, or nested mutable objects inside a data class are shared between copies.
+- **cause**: Kotlin's `data class` `.copy()` is a shallow copy. Nested mutable objects (e.g., `MutableList`, mutable sub-data-classes) are not deep-copied — both the original and the copy reference the same mutable object.
+- **strategy**: 1. Read the data class definition — identify any mutable collection or mutable sub-object fields. 2. When copying, explicitly copy mutable fields: `original.copy(items = original.items.toMutableList())`. 3. Prefer immutable collections (`List`, `Map`, `Set`) in data classes and replace the whole list on update rather than mutating in place. 4. If deep copy is frequently needed, implement a `deepCopy()` extension function. 5. Use `@Immutable` annotation with Compose if used in UI state.
+- **toolSequence**: grep (data class name) → file_read (field types) → file_read (copy usage) → file_edit (add explicit field copy for mutable fields)
+- **pitfall**: Do NOT assume `.copy()` is a deep copy — always audit mutable nested fields after using it.
+
+## Verification
+Run: `./gradlew compileKotlin` or `./gradlew build`
+- Exit 0 = no compile errors.
+- For Android: `./gradlew assembleDebug`
+- For lint: `./gradlew lint`
+
+## Validation Checklist
+- [ ] No `!!` operators without an accompanying comment proving non-null at that point
+- [ ] No `GlobalScope.launch` — use `viewModelScope` or `lifecycleScope`
+- [ ] All `when` on sealed classes cover every subclass explicitly (no `else` hiding new cases)
+- [ ] `var` used only where mutation is necessary — smart cast issues resolved with `val` capture
+- [ ] Data class mutable fields explicitly copied when using `.copy()`
+- [ ] Coroutine scopes cancelled in lifecycle teardown (`onCleared`, `onDestroy`)
+- [ ] `./gradlew compileKotlin` exits 0

package/dist/skills/skills/languages/lua.md

@@ -0,0 +1,79 @@
+## Identity
+- domain: lua
+- type: language
+- confidence: 0.88
+
+# Lua — Error Pattern Reference
+
+Read the exact error message including the file path and line number. Lua errors are often runtime-only — the interpreter does not check types or undefined variables at load time.
+
+## Error Code Quick Reference
+- **"attempt to index a nil value"** — Accessing a field on a nil variable or missing table key.
+- **"attempt to call a nil value"** — Calling a function that is nil (not found or not loaded).
+- **"attempt to perform arithmetic on a nil value"** — Math on nil variable.
+- **"attempt to concatenate a nil value"** — String concatenation with nil.
+- **"stack overflow"** — Infinite recursion without a base case.
+- **"bad argument #N to 'func'"** — Wrong type passed to a built-in or type-checked function.
+- **"table index is nil"** — Using nil as a table key: `t[nil] = value`.
+- **"module 'x' not found"** — `require` failed; package.path doesn't include the module location.
+
+## Known Error Patterns
+
+### Nil Value Error — Missing Table Key
+- **Symptom**: `attempt to index a nil value (global 'config')` or `attempt to index a nil value (field 'options')`; crash on accessing a nested field.
+- **Cause**: A table key that was expected to exist returns `nil` in Lua — there is no KeyError, just silent nil. Chaining dot access on a nil result then causes a crash: `config.database.host` crashes if `config.database` is nil.
+- **Strategy**: 1. Add nil guards before table access: `if config and config.database then ... end`. 2. Provide defaults with `or`: `local host = (config and config.database and config.database.host) or "localhost"`. 3. Write a safe-get helper: `local function get(t, ...) local v = t; for _, k in ipairs({...}) do if type(v) ~= "table" then return nil end; v = v[k] end; return v end`. 4. For optional config, always initialize tables with defaults before use.
+- **Tool sequence**: file_read (nil access location) → file_edit (add nil check guards or default values)
+- **Pitfall**: Do NOT use `pcall` to silently swallow nil errors — use it to catch errors but always log the error message for diagnosis.
+
+### Global vs Local Variable Confusion
+- **Symptom**: A variable modified in a function doesn't change the outer value (or unexpectedly does); different files sharing the same global name clobber each other; module-level state bleeds between tests.
+- **Cause**: In Lua, variables are global by default unless declared with `local`. `x = 5` sets a global; `local x = 5` creates a local. A common mistake: forgetting `local` inside a function creates an unintended global that persists and conflicts.
+- **Strategy**: 1. Declare all variables with `local` unless global access is explicitly intended. 2. Use `luacheck` to detect global variable usage: it warns on undefined globals and accidental global creation. 3. Enforce strict mode in environments that support it: `local _ENV = setmetatable({}, {__newindex = function() error("global write") end, __index = _G})`. 4. For modules, return a table of public functions instead of using globals. 5. Grep for assignments without `local` at function scope.
+- **Tool sequence**: shell_exec (`luacheck <file.lua>`) → file_read → file_edit (add `local` keyword to variable declarations)
+- **Pitfall**: Do NOT add `local` to a variable that is intentionally global (e.g., a registered callback that another module reads) — understand the scoping intent before adding `local`.
+
+### 1-Based Indexing Error — Off-By-One in Arrays
+- **Symptom**: Last element of a table is not processed; first element is skipped; `table[0]` returns nil when the array has elements.
+- **Cause**: Lua arrays are 1-indexed by convention — `t[1]` is the first element, `t[#t]` is the last. Programmers from C, Python, or JavaScript expect 0-based indexing. `t[0]` is a valid key (Lua tables have no restriction) but it is not part of the array sequence and `#t` ignores it.
+- **Strategy**: 1. Loops should start at `1`: `for i = 1, #t do`. 2. The last element is `t[#t]`, not `t[#t - 1]`. 3. For string operations, `string.sub(s, 1, 1)` is the first character, `string.sub(s, -1)` is the last. 4. When interfacing with C APIs that return 0-based indices, add 1 before using as a Lua table index. 5. Use `ipairs` for forward iteration over sequences — it starts at 1 and stops at the first nil.
+- **Tool sequence**: grep (`\[0\]`, `for i = 0`) → file_read → file_edit (fix to 1-based indices)
+- **Pitfall**: Do NOT use `pairs` where you need ordered array iteration — `pairs` has undefined order. Use `ipairs` for arrays.
+
+### Metamethod Not Set — __index Missing for OOP
+- **Symptom**: `attempt to index a nil value (method 'draw')` when calling a method on an "object"; the method is defined in a base class but not accessible on instances.
+- **Cause**: Lua does not have built-in OOP. The common pattern uses metatables: `setmetatable(instance, {__index = BaseClass})`. If `__index` is not set, method lookups fall through to nil. Forgetting to call the constructor or set the metatable on instances breaks method dispatch.
+- **Strategy**: 1. Verify the class constructor sets the metatable: `setmetatable(self, ClassName); ClassName.__index = ClassName`. 2. Check that `ClassName.__index = ClassName` is set (or `__index` points to the methods table). 3. For inheritance: `setmetatable(Child, {__index = Parent})` — missing this breaks parent method access. 4. Use a consistent OOP pattern (e.g., `middleclass`, `30log`) rather than rolling your own metamethod setup, which is error-prone.
+- **Tool sequence**: grep (`setmetatable`, `__index`) → file_read (class definition) → file_edit (add missing __index assignment)
+- **Pitfall**: Do NOT set `__index = self` on an instance — it should be `__index = ClassName` (the class table), not the instance itself.
+
+### Coroutine Yield Across C Boundary
+- **Symptom**: `attempt to yield from outside a coroutine` or `attempt to yield across a C-call boundary`; coroutine yields work in pure Lua but crash when called from C callbacks.
+- **Cause**: When Lua is embedded in a C application (e.g., Nginx/OpenResty, game engines), some C API callbacks don't support Lua coroutine yields. The Lua C API `lua_yield` cannot be called from a C function that was itself called from a C function not designed for yielding.
+- **Strategy**: 1. Identify which C callbacks are involved in the yield path (Nginx directives, game engine callbacks). 2. Check if the embedding environment provides coroutine-compatible APIs (e.g., OpenResty's `ngx.sleep` instead of OS sleep). 3. Use `coroutine.wrap` with `pcall` to catch yield errors gracefully. 4. Restructure to avoid yielding from within C-initiated callbacks — use event-driven callbacks instead of blocking yields. 5. Use `lua_isyieldable()` to check before yielding.
+- **Tool sequence**: grep (`coroutine.yield`, `coroutine.resume`) → file_read → file_edit (use environment-specific non-blocking alternatives)
+- **Pitfall**: Do NOT wrap a yield in `pcall` to suppress the error — the coroutine does not actually yield and the operation blocks. Use environment-provided async APIs.
+
+### require Path Not Found — Module Loading Failure
+- **Symptom**: `module 'mymodule' not found: no field package.preload['mymodule']...`; the file exists but Lua cannot find it.
+- **Cause**: Lua searches `package.path` for modules (`.lua` files) and `package.cpath` for C modules (`.so`/`.dll`). The default path may not include the project directory. Module names use dots as separators which map to directory separators.
+- **Strategy**: 1. Print the current path: `print(package.path)`. 2. Add the project root to the path: `package.path = package.path .. ";./?.lua;./src/?.lua"` (or set `LUA_PATH` environment variable). 3. Check module name matches file path: `require("utils.helpers")` looks for `utils/helpers.lua`. 4. For LuaRocks modules, verify installation: `luarocks list`. 5. In embedded Lua, the host application may need to set `package.path` explicitly.
+- **Tool sequence**: shell_exec (`lua -e "print(package.path)"`) → file_read (module loading code) → file_edit (add correct path to package.path)
+- **Pitfall**: Do NOT use absolute paths in `require()` — always use relative module paths with dots. Absolute paths are not portable.
+
+## Verification
+Run: `luac -p <file.lua>` for syntax check, then `lua <file.lua>` for runtime.
+- Run luacheck: `luacheck . --globals <known_globals>` — zero errors, zero warnings.
+- Run LuaUnit or busted test suite: all tests must pass.
+
+## Validation Checklist
+- [ ] All variables declared with `local` unless intentionally global
+- [ ] All table accesses guarded with nil checks or `and` short-circuit
+- [ ] Array loops start at index `1`, not `0`
+- [ ] All class definitions have `ClassName.__index = ClassName` set
+- [ ] `setmetatable` called on every class instance in the constructor
+- [ ] No coroutine yields inside C callback boundaries
+- [ ] `require` paths use dot notation and match the actual file structure
+- [ ] `package.path` configured correctly for the project layout
+- [ ] luacheck passes with no undefined globals
+- [ ] All error paths use `error()` or return `nil, error_message` — not silent nil returns

package/dist/skills/skills/languages/php.md

@@ -0,0 +1,73 @@
+## Identity
+- domain: php
+- type: language
+- confidence: 0.91
+
+# PHP — Error Pattern Reference
+
+Read the full error message including file path, line number, and error level (Notice, Warning, Fatal). PHP distinguishes levels — a Notice does not stop execution but a Fatal does.
+
+## Error Level Quick Reference
+- **Parse error** — Syntax error; PHP cannot compile the file.
+- **Fatal error** — Unrecoverable; execution stops.
+- **Warning** — Non-fatal but usually indicates a bug.
+- **Notice** — Informational; often undefined variable or index.
+- **Deprecated** — API usage that will be removed in a future version.
+
+## Known Error Patterns
+
+### Undefined variable
+- **Symptom**: `Notice: Undefined variable: foo` or in PHP 8: `Warning: Undefined variable $foo`
+- **Cause**: Using a variable that has not been assigned in the current scope. Common when a conditional assignment is skipped or a parameter name is misspelled.
+- **Strategy**: 1. Read the function or scope where the variable is used. 2. Trace all code paths — is there a branch where the variable is never set? 3. Add a default assignment before the conditional: `$foo = null;` or `$foo = [];`. 4. For superglobals (`$_GET`, `$_POST`), use `isset` or `??`: `$val = $_GET['key'] ?? null`.
+- **Tool sequence**: file_read (function scope) → grep (all assignments to variable) → file_edit (add default assignment)
+- **Pitfall**: Do NOT suppress with `@` operator. Fix the missing assignment.
+
+### Call to undefined function
+- **Symptom**: `Fatal error: Call to undefined function foo()`
+- **Cause**: Function not defined in scope. Missing `require`/`include` for the file containing it, missing Composer autoload, or a misspelled function name.
+- **Strategy**: 1. Grep for the function definition across the project. 2. If found, check whether the file containing it is required at the call site. 3. If it is a Composer package function, verify `require 'vendor/autoload.php'` is present at the entry point. 4. Check PHP extension functions — the required extension may not be loaded (check `php.ini` with `phpinfo()`).
+- **Tool sequence**: grep (`function foo`) → file_read (entry point for autoload) → shell_exec (`php -m` for extensions)
+- **Pitfall**: Do NOT copy-paste the function definition inline. Find the canonical source and require it properly.
+
+### Cannot use object of type stdClass as array
+- **Symptom**: `Fatal error: Cannot use object of type stdClass as array`
+- **Cause**: `json_decode()` without the second argument returns an `stdClass` object, not an array. Accessing it with `$result['key']` fails; `$result->key` is required.
+- **Strategy**: 1. Find the `json_decode` call. 2. Pass `true` as the second argument to return an associative array: `json_decode($json, true)`. 3. If the type needs to be `stdClass` in some places, use object notation consistently: `$result->key`.
+- **Tool sequence**: grep (`json_decode`) → file_read → file_edit (add second argument `true`)
+- **Pitfall**: Do NOT cast `(array)` on nested objects — it only shallowly converts the top level.
+
+### Type juggling bug: == vs ===
+- **Symptom**: Comparisons return unexpected truthy/falsy results. E.g., `"0" == false` is true, `"1" == true` is true, `0 == "foo"` is true (PHP < 8), `"1" == "01"` is true.
+- **Cause**: PHP's loose comparison (`==`) coerces types. This causes subtle bugs in password comparison, status checks, and array search results.
+- **Strategy**: 1. Grep all `==` comparisons involving variables that could be mixed types (strings from user input, database fields, `in_array` calls). 2. Replace with strict `===` wherever type equality must be enforced. 3. For `in_array`, pass `true` as the third argument: `in_array($val, $arr, true)`.
+- **Tool sequence**: grep (`==\s`) → file_read (comparison context) → file_edit (replace with `===`)
+- **Pitfall**: Do NOT globally replace all `==` with `===` — some intentional type-coercing comparisons may exist. Review each case.
+
+### Composer autoload not loaded
+- **Symptom**: `Fatal error: Class 'Vendor\Package\Foo' not found` even though the package is in `composer.json`
+- **Cause**: `require_once __DIR__ . '/vendor/autoload.php';` is missing from the entry point, or the dependencies were not installed (`vendor/` directory absent).
+- **Strategy**: 1. Check the entry point file (usually `index.php`, `bootstrap.php`, or the framework entry). 2. Verify `require_once __DIR__ . '/vendor/autoload.php';` is the first require. 3. Run `composer install` if `vendor/` is missing. 4. If using a namespace, verify `composer.json` has the correct `autoload.psr-4` mapping and run `composer dump-autoload`.
+- **Tool sequence**: file_read (entry point) → shell_exec (`ls vendor/`) → shell_exec (`composer install` or `composer dump-autoload`)
+- **Pitfall**: Do NOT manually add `require` statements for individual Composer classes. Fix the autoload setup.
+
+### Undefined array key / index
+- **Symptom**: `Warning: Undefined array key "foo"` or `Notice: Undefined index: foo`
+- **Cause**: Accessing an array key that does not exist. Common with form inputs, API responses, or optional config keys.
+- **Strategy**: 1. Use `isset($arr['key'])` or the null coalescing operator `$arr['key'] ?? null` before accessing. 2. For required keys, throw an explicit exception or return an error rather than silently returning null.
+- **Tool sequence**: file_read (array access line) → file_edit (add `isset` check or `??` operator)
+- **Pitfall**: Do NOT use `@$arr['key']` to suppress the warning. Use `??` or `isset`.
+
+## Verification
+Run: `php -l <file>` for syntax check.
+- For full project: `./vendor/bin/phpstan analyse` (if PHPStan is configured) or `./vendor/bin/psalm`.
+- Always run `composer install` before testing if `vendor/` is absent or stale.
+
+## Validation Checklist
+- [ ] `php -l` exits 0 for all modified files
+- [ ] All `json_decode` calls pass `true` as second arg when array access is used
+- [ ] All security-sensitive comparisons use `===` not `==`
+- [ ] `require_once __DIR__ . '/vendor/autoload.php'` present in entry point
+- [ ] No `@` error suppression operator added
+- [ ] All `$_GET`/`$_POST`/`$_REQUEST` accesses use `??` or `isset`
+- [ ] `in_array` calls use strict mode (`true` as third argument) for type-sensitive checks

package/dist/skills/skills/languages/python.md

@@ -0,0 +1,89 @@
+## Identity
+- domain: python
+- type: language
+- confidence: 0.9
+
+# Python — Common Errors and Patterns
+
+Read the full traceback from bottom to top. The bottom frame is the immediate cause; the top is the entry point.
+
+## Known Error Patterns
+
+### ModuleNotFoundError
+- **Symptom**: `ModuleNotFoundError: No module named 'x'`
+- **Cause**: Package not installed in the active environment, wrong virtual environment active, or a relative import missing the leading dot (`.`).
+- **Strategy**: 1. Run `pip show <package>` to confirm installation. 2. Confirm the correct virtualenv is active (`which python`). 3. If it is a local module, check whether the import should be relative (`.module`) vs. absolute. 4. If the package is missing, install it and add to requirements.txt or pyproject.toml.
+- **Tool sequence**: shell_exec (`pip show package`) → file_read (requirements.txt or pyproject.toml) → shell_exec (`pip install package`) → file_edit (update requirements)
+- **Pitfall**: Do NOT install globally if the project uses a virtualenv. Installing globally can shadow the wrong version and break other projects.
+
+### IndentationError / TabError
+- **Symptom**: `IndentationError: unexpected indent`, `IndentationError: expected an indented block after ...`, or `TabError: inconsistent use of tabs and spaces`
+- **Cause**: Mixed tabs and spaces in the same file, or wrong indent level after a block opener (`def`, `if`, `for`, `class`, `with`, `try`).
+- **Strategy**: 1. Run `python -m py_compile file.py` to get the exact line. 2. Read that line and the line above it. 3. Use `expand` or editor settings to convert all tabs to 4 spaces. 4. Run `black file.py` or `autopep8 --in-place file.py` to auto-fix indentation.
+- **Tool sequence**: shell_exec (`python -m py_compile file.py`) → file_read (reported line) → shell_exec (`black file.py` or `autopep8 --in-place file.py`)
+- **Pitfall**: Do NOT fix indentation by eye in a file with mixed tabs and spaces. Convert all tabs to spaces first, then fix the structure.
+
+### AttributeError: 'NoneType' has no attribute 'x'
+- **Symptom**: `AttributeError: 'NoneType' object has no attribute 'foo'`
+- **Cause**: A variable expected to hold an object is `None`. Typically from a function that returns `None` on failure, an uninitialized field, or a failed ORM query.
+- **Strategy**: 1. Find where the variable is assigned (trace the traceback up). 2. Determine whether `None` is a valid value or an error. 3. If `None` is unexpected, add an assertion or raise early: `if obj is None: raise ValueError(...)`. 4. If `None` is valid, add a guard: `if obj is not None: obj.foo`.
+- **Tool sequence**: file_read (assignment site from traceback) → file_edit (add None check or early raise)
+- **Pitfall**: Do NOT use `getattr(obj, 'foo', None)` to hide the `None` object — that shifts the error downstream. Fix the root cause.
+
+### TypeError — Wrong Number of Arguments
+- **Symptom**: `TypeError: foo() takes X positional arguments but Y were given` or `TypeError: foo() missing Y required positional arguments`
+- **Cause**: Calling a function with wrong argument count. Common: forgetting `self` when calling a method as a function, or passing too many positional args when some should be keyword args.
+- **Strategy**: 1. Grep the function definition to read its signature. 2. Count the parameters. 3. Check if it is a method (requires `self`). 4. Fix the call site to match the signature.
+- **Tool sequence**: grep (function/method name `def`) → file_read → file_edit (fix call site)
+- **Pitfall**: Do NOT add `*args` or `**kwargs` to the function signature to silence the error. Fix the call.
+
+### TypeError — Unsupported Operand Types
+- **Symptom**: `TypeError: unsupported operand type(s) for +: 'int' and 'str'`
+- **Cause**: Mixing incompatible types in an arithmetic or comparison operation. Often from user input (always a string) or mixed data sources.
+- **Strategy**: 1. Read the line in the traceback. 2. Identify which variable has the unexpected type. 3. Add an explicit conversion: `int(x)`, `str(x)`, `float(x)` at the right point. 4. Add a type check if the input source is untrusted.
+- **Tool sequence**: file_read (traceback line) → file_edit (add explicit conversion)
+- **Pitfall**: Do NOT add a bare `try/except` around the operation to hide the error. Convert the type before the operation.
+
+### KeyError on Dictionary Access
+- **Symptom**: `KeyError: 'foo'`
+- **Cause**: Accessing `dict['key']` when the key does not exist.
+- **Strategy**: 1. Use `dict.get('key')` to return `None` when missing, or `dict.get('key', default)` for a default value. 2. If the key must exist, add an assertion or raise with a descriptive message: `if 'key' not in d: raise KeyError(f"Expected key 'key' in {d}")`. 3. If reading from external data, validate the schema before access.
+- **Tool sequence**: file_read (traceback line) → file_edit (replace `dict[key]` with `dict.get(key)` or add guard)
+- **Pitfall**: Do NOT wrap the access in bare `except KeyError: pass`. That hides missing data bugs.
+
+### Circular Import
+- **Symptom**: `ImportError: cannot import name 'X' from partially initialized module 'y'`
+- **Cause**: Module A imports from module B, and module B imports from module A at the top level.
+- **Strategy**: 1. Grep import statements in both modules to confirm the cycle. 2. Move shared types or functions to a third module that neither imports from the other two. 3. Alternatively, use a lazy import (move the import inside the function that needs it). 4. Avoid restructuring via `importlib.import_module` — that just hides the problem.
+- **Tool sequence**: grep (import statements in both modules) → file_read → file_edit (move shared code to third module or use lazy import)
+- **Pitfall**: Do NOT move the import to the bottom of the file as a workaround. That makes the dependency order implicit and fragile.
+
+### RecursionError — Maximum Depth Exceeded
+- **Symptom**: `RecursionError: maximum recursion depth exceeded`
+- **Cause**: A recursive function has no base case, or the base case is never reached for the given input, or two functions call each other indefinitely.
+- **Strategy**: 1. Read the function and identify the base case. 2. Add a print or log to confirm the base case is reachable. 3. If depth is legitimately large, increase with `sys.setrecursionlimit(N)` as a last resort. 4. Convert deep recursion to an iterative loop with an explicit stack.
+- **Tool sequence**: file_read (recursive function) → file_edit (add/fix base case or convert to loop)
+- **Pitfall**: Do NOT just increase the recursion limit without fixing the base case — that defers the crash.
+
+### ValueError from Type Conversion
+- **Symptom**: `ValueError: invalid literal for int() with base 10: 'abc'`
+- **Cause**: Attempting to convert a string that does not represent the target type.
+- **Strategy**: 1. Validate the input before conversion. 2. Wrap in a try/except and handle the ValueError specifically. 3. For user-facing input, return an error message rather than crashing.
+- **Tool sequence**: file_read (conversion site) → file_edit (add try/except ValueError or pre-validation)
+- **Pitfall**: Do NOT use a bare `except:` or `except Exception:`. Catch `ValueError` specifically.
+
+## Verification
+- Syntax: `python -m py_compile file.py` — exit 0 means no syntax errors.
+- Tests: `pytest` or `python -m pytest` — all tests must pass.
+- Type check (if project uses mypy): `mypy .` — zero errors.
+- Linting: `flake8 .` or `ruff check .`
+
+## Validation Checklist
+- [ ] `python -m py_compile` exits 0 on all modified files
+- [ ] All imports resolve in the active virtual environment
+- [ ] No mixed tabs and spaces (run `black` or `autopep8`)
+- [ ] All None-returning function calls guarded before attribute access
+- [ ] All dict accesses use `.get()` or have key existence check
+- [ ] Recursive functions have a reachable base case
+- [ ] Tests pass with `pytest`
+- [ ] mypy exits 0 if the project has a mypy configuration