@yuaone/core 0.8.4 → 0.9.0

package/dist/skills/languages/typescript.md

@@ -0,0 +1,110 @@
+## Identity
+- domain: typescript
+- type: language
+- confidence: 0.95
+
+# TypeScript — Error Pattern Reference
+
+Read the exact error code first. Each TS error has a precise meaning — do not guess from the message alone.
+
+## Error Code Quick Reference
+- **TS2345** — Argument type mismatch. Read the function signature.
+- **TS2322** — Assignment type mismatch. Read the variable declaration.
+- **TS2304** — Cannot find name. Missing import or typo.
+- **TS2339** — Property does not exist on type. Wrong type assumption.
+- **TS2307** — Cannot find module. Missing package or wrong path.
+- **TS7006** — Parameter implicitly has 'any'. Add explicit type.
+- **TS2531** — Object is possibly null. Add null check.
+- **TS2532** — Object is possibly undefined. Add undefined check.
+- **TS2769** — No overload matches. Read all overload signatures.
+- **TS1005** — Syntax error. Read the exact line and column.
+- **TS2741** — Missing required properties in object literal.
+- **TS2366** — Function lacks ending return statement.
+- **TS2411** — Index signature incompatible.
+- **TS4023** — Exported expression refers to unexported type.
+
+## Known Error Patterns
+
+### TS2345 — Wrong Argument Type
+- **Symptom**: `Argument of type 'X' is not assignable to parameter of type 'Y'`
+- **Cause**: Passing wrong type to function. Common cases: string where number expected, union type wider than parameter, optional field passed as required.
+- **Strategy**: 1. Read the exact function signature by grepping the function name and reading its definition. 2. Identify which parameter is mismatched. 3. Fix the call site by passing the correct type or narrowing the value. Only add a type assertion if you have verified the runtime type is correct.
+- **Tool sequence**: grep (function name) → file_read (definition) → file_edit (fix call site)
+- **Pitfall**: Do NOT cast to `any` as a first resort. Read the actual expected type before touching the call site.
+
+### TS2322 — Wrong Assignment Type
+- **Symptom**: `Type 'X' is not assignable to type 'Y'`
+- **Cause**: Assigning a value to a variable whose declared type does not accept it. Often: number assigned to string, wider union assigned to narrower union, optional assigned to required.
+- **Strategy**: 1. Find the variable declaration (grep or file_read). 2. Decide whether the declaration is wrong (widen it) or the assigned value is wrong (narrow/convert it). 3. Fix the narrower of the two.
+- **Tool sequence**: grep (variable name) → file_read (declaration) → file_edit
+- **Pitfall**: Do NOT widen the type to `any` or `unknown` unless the variable genuinely needs to hold arbitrary values.
+
+### TS2339 — Property Does Not Exist
+- **Symptom**: `Property 'x' does not exist on type 'Y'`
+- **Cause**: Accessing a property that is not in the type definition. Common after API response parsing, JSON.parse, or accessing a subtype's property on a base type.
+- **Strategy**: 1. Grep the interface or type definition. 2. Check if the property exists but on a subtype — use type narrowing (`if ('x' in obj)` or `instanceof`). 3. If the property should exist, add it to the interface. 4. If it is conditional, make it optional (`x?: T`).
+- **Tool sequence**: grep (interface name or type name) → file_read → file_edit
+- **Pitfall**: Do NOT extend the interface blindly. Confirm the property actually exists at runtime before adding it to the type.
+
+### TS2531 / TS2532 — Possibly Null or Undefined
+- **Symptom**: `Object is possibly 'null'` or `Object is possibly 'undefined'`
+- **Cause**: Using a value that TypeScript knows might be null or undefined without a guard.
+- **Strategy**: Add an explicit check: `if (x !== null && x !== undefined)`, or use nullish coalescing `x ?? defaultValue`, or optional chaining `x?.property`. For function returns, add a null return guard at the top.
+- **Tool sequence**: file_read (lines around error) → file_edit (add null check or optional chain)
+- **Pitfall**: Do NOT use the non-null assertion operator `!` unless you can read code that guarantees non-null at that exact point. Using `!` without proof creates silent runtime crashes.
+
+### TS2307 — Cannot Find Module
+- **Symptom**: `Cannot find module './path' or its corresponding type declarations`
+- **Cause**: Import path wrong, package not installed, missing `@types/` package, or tsconfig path alias not resolving.
+- **Strategy**: 1. Verify the file exists at the import path using shell_exec. 2. Check tsconfig.json for path aliases that might apply. 3. Check package.json for the package. 4. If the package exists but lacks types, install `@types/<package>` or add a `.d.ts` declaration stub.
+- **Tool sequence**: shell_exec (`ls <path>`) → file_read (tsconfig.json) → file_read (package.json) → shell_exec (pnpm add @types/package)
+- **Pitfall**: Do NOT assume the import path is wrong — check tsconfig path aliases before renaming imports.
+
+### TS7006 — Implicit Any on Parameter
+- **Symptom**: `Parameter 'x' implicitly has an 'any' type`
+- **Cause**: Function parameter has no type annotation and TypeScript cannot infer it from context.
+- **Strategy**: Read how the function is called (grep call sites) to determine what type is actually passed. Add that type as an explicit annotation. If multiple types are possible, use a union type.
+- **Tool sequence**: grep (function name call sites) → file_read (definition) → file_edit (add annotation)
+- **Pitfall**: Do NOT write `: any` to satisfy the compiler. Infer the real type from the call sites.
+
+### TS2769 — No Overload Matches
+- **Symptom**: `No overload matches this call` with a list of overload candidates
+- **Cause**: Calling a function with arguments that do not satisfy any of its overload signatures.
+- **Strategy**: 1. Read ALL listed overload signatures in the error output. 2. Identify which argument is causing the mismatch (the error lists which overload got closest). 3. Fix the argument type or add the correct overload if you own the function.
+- **Tool sequence**: file_read (error output fully) → grep (function definition) → file_read → file_edit
+- **Pitfall**: Do NOT add a new overload signature as a first resort if you do not own the library. Fix the call site argument.
+
+### TS2741 — Missing Required Properties
+- **Symptom**: `Type 'X' is missing the following properties from type 'Y': a, b, c`
+- **Cause**: Object literal or variable missing required fields for the target interface.
+- **Strategy**: 1. Read the target interface definition. 2. Add all missing required properties. 3. If a property should be optional, make it optional in the interface (if you own it).
+- **Tool sequence**: grep (interface name) → file_read → file_edit (add missing fields)
+- **Pitfall**: Do NOT make all fields optional to silence the error. Required fields exist for a reason.
+
+### Type Narrowing Failure
+- **Symptom**: TypeScript still shows a union type inside a conditional block that should have narrowed it
+- **Cause**: The narrowing condition uses a pattern TypeScript does not recognize, or a type guard function is not declared with a type predicate.
+- **Strategy**: Use `typeof x === "string"`, `x instanceof ClassName`, discriminant property check (`x.kind === "foo"`), or a type predicate function `(x): x is SpecificType`. Ensure the check is directly in the condition — TypeScript does not follow complex indirect narrowing.
+- **Tool sequence**: file_read (narrowing block) → file_edit (replace condition with recognized narrowing pattern)
+- **Pitfall**: Do NOT use `x as SpecificType` inside the block to work around failed narrowing. Fix the condition.
+
+### Circular Type Reference
+- **Symptom**: `Type alias 'X' circularly references itself` or extremely slow tsc
+- **Cause**: Type A references Type B which references Type A directly.
+- **Strategy**: Break the cycle by introducing an intermediate interface or by using `interface` instead of `type` alias (interfaces handle some recursive cases). Extract shared fields into a base interface.
+- **Tool sequence**: grep (type name references) → file_read → file_edit (introduce base interface)
+- **Pitfall**: Do NOT wrap in `any` to break the cycle. The circular reference usually signals a design issue.
+
+## Verification
+Run: `tsc --noEmit`
+- Exit 0 with no output = success.
+- Any line starting with `error TS` = failure. The format is `file(line,col): error TSxxxx: message`.
+- Always read the full error line including file path and column number before acting.
+
+## Validation Checklist
+- [ ] `tsc --noEmit` exits 0
+- [ ] No `as any` added without a comment explaining the runtime guarantee
+- [ ] No non-null assertions `!` added without a comment citing the proof
+- [ ] All new interfaces have required fields marked optional only if they can genuinely be absent
+- [ ] No `@ts-ignore` or `@ts-expect-error` added to suppress errors without comment
+- [ ] Import paths verified to exist on disk or in tsconfig aliases

package/dist/skills/plan.md

@@ -0,0 +1,49 @@
+## Identity
+- domain: general
+- type: plan
+- confidence: 0.8
+
+# Plan — Decompose, Sequence, Risk
+
+Break the goal into tasks that can be executed independently. The plan is wrong if any task requires knowing the output of a parallel task.
+
+## Workflow
+1. **Understand** — Read relevant files. Do not plan from assumptions.
+2. **Decompose** — Break goal into tasks. Each task = one logical change.
+3. **Sequence** — Order by dependencies. What must be done before what?
+4. **Assign** — Which files does each task touch? (No two tasks touch the same file.)
+5. **Risk** — What can go wrong? What is the rollback?
+
+## Task Format
+Each task must specify:
+- Goal (one sentence)
+- Files to create/modify
+- Dependencies (which tasks must complete first)
+- Verification (how to confirm it worked)
+
+## Known Error Patterns
+
+### Over-decomposed Tasks
+- **Symptom**: 20+ tasks for what should be a 3-task change
+- **Cause**: Planning at line-level instead of logical-change level
+- **Strategy**: Merge tasks that always change together into one task
+- **Pitfall**: Do NOT create a task for each file if they are all part of one logical change.
+
+### Under-specified Verification
+- **Symptom**: Task says "done" but it is unclear what "done" means
+- **Cause**: No concrete verification step defined
+- **Strategy**: Every task needs: run X command, see Y output
+- **Pitfall**: Do NOT write "test it works" — write the exact command and expected output.
+
+### Missing Rollback
+- **Symptom**: Mid-way through plan, something breaks and there is no way back
+- **Cause**: No checkpoint or rollback strategy
+- **Strategy**: For any plan with 4+ tasks, define a rollback point (git stash, feature flag, etc.)
+- **Pitfall**: Do NOT start a multi-file refactor without a rollback strategy.
+
+## Validation Checklist
+- [ ] Each task has a single clear goal
+- [ ] No two parallel tasks modify the same file
+- [ ] Dependencies between tasks are explicit
+- [ ] Each task has a concrete verification step
+- [ ] Rollback strategy defined for 4+ task plans

package/dist/skills/refactor.md

@@ -0,0 +1,46 @@
+## Identity
+- domain: general
+- type: refactor
+- confidence: 0.85
+
+# Refactor — Preserve Behavior, Improve Structure
+
+Behavior must be identical before and after. Tests are your proof.
+
+## Workflow
+1. **Baseline** — Run test suite. All tests must pass. Record the result.
+2. **Impact map** — Grep for all usages of what you are changing. List every file.
+3. **One change** — Make one structural change at a time.
+4. **Verify** — Run tests. Must still pass.
+5. **Repeat** — Next structural change.
+6. **Commit** — Each logical refactor is its own commit.
+
+## Known Error Patterns
+
+### Partial Rename
+- **Symptom**: Build error or runtime failure after renaming a function/variable
+- **Cause**: Some call sites not updated
+- **Strategy**: grep ALL usages before renaming. Update every occurrence.
+- **Tool sequence**: grep (exact name) → file_read (each result) → file_edit (all occurrences) → shell_exec (build)
+- **Pitfall**: Do NOT rename without grepping first. IDEs miss dynamic usages.
+
+### Changed Interface, Missed Consumers
+- **Symptom**: Tests pass for the changed file, but integration tests fail
+- **Cause**: Callers of the changed interface not updated
+- **Strategy**: 1. grep for import of the changed module 2. Read each consumer 3. Update to new interface
+- **Tool sequence**: grep (from.*moduleName, require.*moduleName) → file_read → file_edit
+- **Pitfall**: Do NOT update the implementation without updating all consumers.
+
+### Behavior Change During Refactor
+- **Symptom**: Tests that were passing now fail after "only structural" changes
+- **Cause**: Subtle logic change introduced during structural refactor
+- **Strategy**: 1. Stop. 2. git diff the changes. 3. Identify which line changed behavior. 4. Revert behavior, keep structure.
+- **Tool sequence**: shell_exec (git diff) → file_read → file_edit (revert behavior change only)
+- **Pitfall**: Do NOT proceed with failing tests. Fix the regression immediately.
+
+## Validation Checklist
+- [ ] Test suite passes before refactor starts (baseline)
+- [ ] All usages of changed symbols grepped and listed
+- [ ] Test suite passes after each individual change
+- [ ] No behavior changes (same inputs produce same outputs)
+- [ ] Build passes

package/dist/skills/security-scan.md

@@ -0,0 +1,59 @@
+## Identity
+- domain: security
+- type: scan
+- confidence: 0.9
+
+# Security Scan — OWASP Top 10 Patterns
+
+Scan for vulnerabilities before they reach production. Each pattern below is a real-world attack vector.
+
+## Scan Order
+1. Injection (SQL, shell, LDAP, XML)
+2. Secrets and credentials in code
+3. Authentication and authorization gaps
+4. Insecure deserialization
+5. Sensitive data exposure
+
+## Known Error Patterns
+
+### SQL Injection
+- **Symptom**: User input concatenated directly into SQL string
+- **Cause**: String interpolation used instead of parameterized queries
+- **Strategy**: 1. Grep for string concatenation with SQL keywords 2. Replace with parameterized queries or ORM methods
+- **Tool sequence**: grep (SELECT.*+) → file_read → file_edit
+- **Pitfall**: Do NOT use string replacement as a sanitization method. Use parameterized queries only.
+
+### Shell Injection
+- **Symptom**: User input passed to shell command execution
+- **Cause**: exec(userInput), shell=True with dynamic input, template string in subprocess
+- **Strategy**: 1. Grep for shell=True, exec(, subprocess with dynamic args 2. Replace with argument arrays, never shell strings
+- **Tool sequence**: grep (shell=True) → file_read → file_edit
+- **Pitfall**: Do NOT use shell=True with any user-controlled input, ever.
+
+### Hardcoded Secrets
+- **Symptom**: API keys, passwords, tokens in source code
+- **Cause**: Developer committed credentials directly
+- **Strategy**: 1. Grep for common secret patterns 2. Move to environment variables 3. Add to .gitignore
+- **Tool sequence**: grep (password=, api_key=, secret=, sk-, Bearer) → file_read → file_edit
+- **Pitfall**: Do NOT just delete the secret — rotate it first, then remove from code.
+
+### Path Traversal
+- **Symptom**: User-supplied file path used without validation
+- **Cause**: open(userPath), readFile(req.params.filename) without sanitization
+- **Strategy**: 1. Validate path is within allowed directory 2. Use path.resolve() and check it starts with allowed base
+- **Tool sequence**: grep (readFile, open(, fs.) → file_read → file_edit
+- **Pitfall**: Do NOT use path.basename() alone — it does not prevent traversal through symlinks.
+
+### Insecure Direct Object Reference
+- **Symptom**: Resource ID from request used directly without ownership check
+- **Cause**: db.find({ id: req.params.id }) without checking userId matches session
+- **Strategy**: Always check that the authenticated user owns the requested resource
+- **Tool sequence**: grep (req.params, req.query) → file_read → file_edit
+- **Pitfall**: Do NOT assume frontend-only authorization is sufficient.
+
+## Validation Checklist
+- [ ] No user input in SQL/shell/LDAP strings
+- [ ] No secrets in source code
+- [ ] All file paths validated against base directory
+- [ ] All resource access checks ownership
+- [ ] Dependencies scanned for known vulnerabilities

package/dist/skills/skills/code-review.md

@@ -0,0 +1,58 @@
+## Identity
+- domain: general
+- type: review
+- confidence: 0.95
+
+# Code Review — Correctness, Security, Performance
+
+Review in priority order: Correctness → Security → Performance → Style.
+Style comments without correctness/security concerns are noise.
+
+## Severity Levels
+- **CRITICAL** — Will cause data loss, security breach, or crash in production. Must fix before merge.
+- **HIGH** — Likely bug under realistic conditions. Fix before merge.
+- **MEDIUM** — Potential issue under edge cases. Fix recommended.
+- **LOW** — Style, readability, minor improvement. Optional.
+
+## Review Checklist
+
+### Correctness
+- [ ] Does the logic match the intended behavior?
+- [ ] Are all edge cases handled (null, empty, boundary)?
+- [ ] Are error conditions handled or explicitly ignored?
+- [ ] Are async operations awaited where needed?
+- [ ] Are race conditions possible?
+
+### Security
+- [ ] User input validated and sanitized before use?
+- [ ] No string interpolation into SQL/shell/HTML?
+- [ ] No secrets, API keys, or credentials in code?
+- [ ] File paths validated to prevent traversal?
+- [ ] Permissions checked before operations?
+
+### Performance
+- [ ] No N+1 queries in loops?
+- [ ] No unbounded operations on user-controlled input size?
+- [ ] Expensive operations cached where appropriate?
+
+## Known Error Patterns
+
+### Logic Bug — Off By One
+- **Symptom**: Array access, loop bounds, or range checks produce wrong results at edges
+- **Cause**: < vs <=, 0 vs 1 as start index, missing last element
+- **Strategy**: Test with length=0, length=1, and at-boundary inputs
+- **Tool sequence**: file_read → grep (similar patterns) → file_edit
+- **Pitfall**: Do NOT approve logic that was not tested at its boundaries.
+
+### Silent Failure
+- **Symptom**: Function catches error and returns undefined/null/false without logging
+- **Cause**: catch block swallows errors
+- **Strategy**: Flag all catch blocks that do not log or rethrow
+- **Tool sequence**: grep (catch) → file_read → comment
+- **Pitfall**: Do NOT approve silent error suppression in production code paths.
+
+## Validation Checklist
+- [ ] All CRITICAL issues flagged
+- [ ] All HIGH issues flagged
+- [ ] Security review completed
+- [ ] Review output formatted as severity-labeled list

package/dist/skills/skills/debug.md

@@ -0,0 +1,45 @@
+## Identity
+- domain: general
+- type: debug
+- confidence: 0.9
+
+# Debug — Reproduce, Trace, Fix, Verify
+
+Always reproduce the bug before touching any code. A fix you can't verify didn't happen.
+
+## Workflow
+1. **Reproduce** — Write a minimal script or test that triggers the bug. Run it. Confirm it fails.
+2. **Trace** — Read the error message completely. Find the deepest frame in YOUR code (not library internals). Read that file.
+3. **Localize** — Grep for the function/symbol in the error. Read 3 levels of call hierarchy.
+4. **Fix** — Smallest change that resolves the root cause. Not the symptom.
+5. **Verify** — Rerun the reproduction script. Run full test suite. Confirm no regressions.
+
+## Known Error Patterns
+
+### Fixing the Wrong Location
+- **Symptom**: Fix applied, error persists or appears elsewhere
+- **Cause**: Patched a caller when the bug is in the callee, or patched a copy/subclass instead of the source
+- **Strategy**: 1. Grep all files containing the error pattern 2. Read the deepest implementation, not the surface call 3. Fix the source, not the symptom
+- **Tool sequence**: grep → file_read (implementation) → file_edit → shell_exec (reproduce)
+- **Pitfall**: Do NOT assume the first grep result is the right location. Read at least 2 candidates.
+
+### Same Error Repeating After Fix
+- **Symptom**: Retried same fix 2+ times, error unchanged
+- **Cause**: Mental model of the bug is wrong
+- **Strategy**: 1. Stop retrying 2. Read the full error message again from scratch 3. Search for the exact error string in the codebase 4. Try a structurally different approach
+- **Tool sequence**: grep (exact error string) → file_read → re-analyze
+- **Pitfall**: Do NOT make a third attempt with the same approach. The model of the problem is broken.
+
+### Test Passes But Bug Persists
+- **Symptom**: Test green, but reported behavior still broken
+- **Cause**: Test does not cover the actual failure path
+- **Strategy**: 1. Read the bug report carefully 2. Write a reproduction that exactly matches the reported flow 3. If test passes, the reproduction is wrong — fix the test first
+- **Tool sequence**: file_read (test) → write_file (reproduction) → shell_exec
+- **Pitfall**: Do NOT declare fixed based on passing tests alone. Run the exact reported scenario.
+
+## Validation Checklist
+- [ ] Reproduction script confirms the bug exists before fix
+- [ ] Reproduction script confirms the bug is gone after fix
+- [ ] Full test suite passes (no regressions)
+- [ ] Root cause addressed, not just symptom
+- [ ] No unrelated code changed

package/dist/skills/skills/languages/bash.md

@@ -0,0 +1,74 @@
+## Identity
+- domain: bash
+- type: language
+- confidence: 0.90
+
+# Bash/Shell — Error Pattern Reference
+
+Always start scripts with `#!/usr/bin/env bash` and `set -euo pipefail`. Most Bash bugs are invisible without these settings. Use `shellcheck` for static analysis.
+
+## Quick Reference
+- **exit code 127** — Command not found.
+- **exit code 126** — Command found but not executable (permission issue).
+- **exit code 1** — General error; check the command's stderr.
+- **unbound variable** — `set -u` is active and an unset variable was used.
+- **broken pipe** — Consumer of a pipeline exited before producer finished.
+
+## Known Error Patterns
+
+### Unbound Variable (set -u)
+- **Symptom**: `bash: FOO: unbound variable` — script exits immediately.
+- **Cause**: `set -u` (nounset) is active and a variable is referenced before being assigned. Common with optional variables, unset environment variables, or array out-of-bounds access.
+- **Strategy**: 1. Identify the variable. 2. Provide a default: `${FOO:-default_value}`. Use `${FOO:-}` (empty default) if an empty string is acceptable. 3. For required variables, add an explicit check before use: `if [[ -z "${FOO:-}" ]]; then echo "FOO is required" >&2; exit 1; fi`.
+- **Tool sequence**: file_read (script lines around error) → file_edit (add `${VAR:-default}` or explicit check)
+- **Pitfall**: Do NOT remove `set -u` to silence the error. The unbound variable is the real bug.
+
+### Word Splitting on Unquoted Variable
+- **Symptom**: Script fails or behaves wrong when a variable contains spaces or glob characters. A filename like `my file.txt` becomes two arguments.
+- **Cause**: Unquoted variable expansion in Bash: `$var` undergoes word splitting and pathname expansion. `"$var"` does not.
+- **Strategy**: 1. Quote all variable expansions: `"$var"`, `"$@"`, `"${array[@]}"`. 2. Run `shellcheck <script>` — it flags all unquoted variables. 3. For arrays, always use `"${arr[@]}"` not `${arr[*]}`.
+- **Tool sequence**: shell_exec (`shellcheck <script>`) → file_read (flagged lines) → file_edit (add quotes)
+- **Pitfall**: Do NOT use single quotes `'$var'` — that prevents expansion entirely. Use double quotes `"$var"`.
+
+### Missing pipefail (set -eo pipefail)
+- **Symptom**: Script reports success even when a command in a pipeline fails. E.g., `false | tee output.txt` exits 0 without `pipefail`.
+- **Cause**: Without `set -o pipefail`, a pipeline's exit code is only the last command's exit code. Failures in earlier pipeline stages are silently ignored.
+- **Strategy**: 1. Add `set -euo pipefail` at the top of every script (after the shebang). 2. For individual pipelines where partial failure is expected, use `set +o pipefail` around that block and restore it after.
+- **Tool sequence**: file_read (top of script) → file_edit (add `set -euo pipefail` after shebang)
+- **Pitfall**: `set -e` alone is not enough for pipelines. Always pair it with `set -o pipefail`.
+
+### Command Not Found in PATH
+- **Symptom**: `command not found: foo` — exit code 127.
+- **Cause**: The command is not in any directory listed in `$PATH`. Common when running scripts as a different user (cron, sudo), in Docker containers with minimal PATH, or when a tool is installed in a non-standard location.
+- **Strategy**: 1. Run `which foo` or `type foo` to verify presence in the current shell. 2. For cron and CI, always use absolute paths: `/usr/bin/foo` or `/usr/local/bin/foo`. 3. If the tool is optional, check before use: `if ! command -v foo &>/dev/null; then echo "foo not installed" >&2; exit 1; fi`. 4. Source the correct profile/environment if the tool is installed via a version manager (nvm, rbenv, pyenv).
+- **Tool sequence**: shell_exec (`which foo`) → shell_exec (`echo $PATH`) → file_edit (use absolute path or add PATH setup)
+- **Pitfall**: Do NOT hardcode `/usr/bin/foo` if the tool may be in `/usr/local/bin` on some systems. Use `command -v` to find it dynamically when portability matters.
+
+### Wrong or Missing Shebang
+- **Symptom**: Script runs with the wrong interpreter (e.g., `sh` instead of `bash`), causing `[[`, arrays, or `local` to fail with syntax errors. Or: permission denied / bad interpreter.
+- **Cause**: Shebang (`#!`) is missing, wrong (`#!/bin/sh` when bashisms are used), or the path is wrong for the target system.
+- **Strategy**: 1. Use `#!/usr/bin/env bash` for portability — `env` finds bash in PATH. 2. Use `#!/bin/sh` only if the script is strictly POSIX sh. 3. If using `[[`, arrays, `local`, `$((...))`, `declare`, or `source`, the shebang must be `bash`. 4. Ensure the file has execute permission: `chmod +x script.sh`.
+- **Tool sequence**: file_read (first line of script) → file_edit (fix shebang) → shell_exec (`chmod +x`)
+- **Pitfall**: On some systems (Alpine Linux, minimal Docker), `/bin/bash` does not exist. Use `#!/usr/bin/env bash` instead.
+
+### Arithmetic — Unintended Glob Expansion
+- **Symptom**: Script exits unexpectedly, or `*` in an expression matches files instead of meaning multiplication.
+- **Cause**: In `[[ ]]` or `$(( ))`, operators like `*`, `?`, `[` have special meanings. Outside these contexts they trigger pathname expansion.
+- **Strategy**: 1. Always use `$(( expr ))` for arithmetic, never `expr` or `let` in new scripts. 2. Quote file patterns that should be treated as literals. 3. Use `[[ ]]` instead of `[ ]` for conditionals — `[[ ]]` does not perform pathname or word splitting.
+- **Tool sequence**: file_read (expression line) → file_edit (replace `[ ]` with `[[ ]]`, wrap arithmetic in `$(( ))`)
+- **Pitfall**: `(( ))` arithmetic returns exit code 1 when the result is 0, which triggers `set -e`. Use `(( expr )) || true` or wrap in an `if`.
+
+## Verification
+Run: `shellcheck <script>` — address all SC#### warnings before deployment.
+- For syntax check only: `bash -n <script>`.
+- Test with edge-case inputs: empty strings, paths with spaces, special characters.
+
+## Validation Checklist
+- [ ] `#!/usr/bin/env bash` on first line
+- [ ] `set -euo pipefail` on second line
+- [ ] `shellcheck` reports zero warnings
+- [ ] All variable expansions quoted: `"$var"`, `"${arr[@]}"`
+- [ ] All external commands referenced by absolute path in cron/CI contexts
+- [ ] `command -v` used to check optional tools before use
+- [ ] No `[ ]` — replaced with `[[ ]]` for conditionals
+- [ ] Arithmetic done in `$(( ))` not with `expr`

package/dist/skills/skills/languages/c.md

@@ -0,0 +1,76 @@
+## Identity
+- domain: c
+- type: language
+- confidence: 0.93
+
+# C — Error Pattern Reference
+
+Compile with warnings enabled: `-Wall -Wextra -Werror`. Many C bugs are silent at compile time but fatal at runtime. Always use a sanitizer (`-fsanitize=address,undefined`) during development.
+
+## Compiler Warning Quick Reference
+- **-Wimplicit-function-declaration** — Calling a function without a prototype.
+- **-Wuninitialized** — Variable used before assignment.
+- **-Wformat** — printf/scanf format string mismatch.
+- **-Wreturn-type** — Missing return in non-void function.
+- **-Warray-bounds** — Array index out of declared bounds (static analysis only).
+- **-Wconversion** — Implicit narrowing conversion.
+- **-Wnull-dereference** — Pointer that may be NULL is dereferenced.
+
+## Known Error Patterns
+
+### Segmentation Fault — Null Pointer Dereference
+- **Symptom**: Program crashes with `Segmentation fault (core dumped)`. GDB shows crash at a pointer dereference.
+- **Cause**: Dereferencing a pointer that is NULL, uninitialized, or has been freed. Common after `malloc` failure (returns NULL), a function returning NULL on error, or using a pointer before assignment.
+- **Strategy**: 1. Run under GDB: `gdb ./program core` then `bt` for backtrace. 2. Identify the faulting line. 3. Add a NULL check before every pointer dereference. 4. For `malloc`: always check `if (ptr == NULL) { /* handle */ }` immediately after allocation. 5. Run with AddressSanitizer: `gcc -fsanitize=address -g` for detailed diagnostics.
+- **Tool sequence**: shell_exec (`gcc -g -fsanitize=address`) → shell_exec (run program) → file_read (faulting line) → file_edit (add NULL check)
+- **Pitfall**: Do NOT assume `malloc` always succeeds. Check the return value every time.
+
+### Buffer Overflow — strcpy / gets / sprintf
+- **Symptom**: Program writes garbage data, crashes unpredictably, or behaves differently between debug and release builds. ASan reports `heap-buffer-overflow` or `stack-buffer-overflow`.
+- **Cause**: `strcpy`, `gets`, `sprintf`, or manual loop writes beyond the allocated buffer. `gets` has no length argument and is inherently unsafe.
+- **Strategy**: 1. Replace `gets` with `fgets(buf, sizeof(buf), stdin)`. 2. Replace `strcpy(dst, src)` with `strncpy(dst, src, sizeof(dst) - 1); dst[sizeof(dst)-1] = '\0';` or use `strlcpy` if available. 3. Replace `sprintf` with `snprintf(buf, sizeof(buf), fmt, ...)`. 4. Audit every buffer write in the file for bound checks.
+- **Tool sequence**: grep (`strcpy\|gets\|sprintf`) → file_read → file_edit (replace with safe variants)
+- **Pitfall**: `strncpy` does NOT null-terminate if the source is longer than n. Always manually set `dst[n-1] = '\0'`.
+
+### Memory Leak — malloc Without free
+- **Symptom**: Program memory usage grows unboundedly. Valgrind reports `definitely lost` or `indirectly lost` blocks.
+- **Cause**: Memory allocated with `malloc`/`calloc`/`realloc` is not freed on all code paths, especially error paths.
+- **Strategy**: 1. Run with Valgrind: `valgrind --leak-check=full ./program`. 2. For each allocation, trace all code paths and confirm `free` is called. 3. Use a consistent pattern: allocate near the start of a scope, free at the end via a cleanup label (`goto cleanup`). 4. Ensure error paths also reach the cleanup label.
+- **Tool sequence**: shell_exec (`valgrind --leak-check=full`) → grep (`malloc\|calloc`) → file_read (all exit paths) → file_edit (add free on all paths)
+- **Pitfall**: Do NOT free a pointer and then use it. Set it to NULL after freeing: `free(p); p = NULL;`.
+
+### Undefined Behavior — Signed Integer Overflow
+- **Symptom**: Unexpected values or crashes only in optimized builds (`-O2`). UBSan reports `signed integer overflow`.
+- **Cause**: Signed integer overflow is undefined behavior in C. Compilers exploit this for optimization, leading to code elimination or wrong values. Common in loop counters, hash functions, and arithmetic.
+- **Strategy**: 1. Compile with `-fsanitize=undefined` to detect overflows. 2. For arithmetic that may overflow, use unsigned types or check before the operation: `if (a > INT_MAX - b) { /* overflow */ }`. 3. Do NOT rely on signed wrap-around behavior.
+- **Tool sequence**: shell_exec (`gcc -fsanitize=undefined -g`) → file_read (arithmetic code) → file_edit (add overflow check or use unsigned)
+- **Pitfall**: Do NOT use `(int)(a + b)` cast to suppress the warning. The overflow happens before the cast.
+
+### Implicit Function Declaration
+- **Symptom**: Compiler warning: `implicit declaration of function 'foo'`; in C99 and later this is an error.
+- **Cause**: Calling a function before its prototype is declared. Missing `#include` for a library function, or a function defined later in the file without a forward declaration.
+- **Strategy**: 1. For standard library functions, identify and add the correct `#include`. 2. For project-internal functions, add a forward declaration at the top of the file or move the definition above the call site. 3. Always compile with `-Wimplicit-function-declaration -Werror`.
+- **Tool sequence**: grep (`#include`) → file_read (function call line) → shell_exec (`man <function>` for required header) → file_edit (add include or forward declaration)
+- **Pitfall**: Do NOT add an implicit `int` return type declaration manually — add the full correct prototype.
+
+### Use of Uninitialized Variable
+- **Symptom**: Garbage values read, random behavior, or UBSan reports `use of uninitialized value`.
+- **Cause**: Local variable declared but not assigned before first read. Conditional initialization that misses a code path.
+- **Strategy**: 1. Compile with `-Wuninitialized`. 2. Initialize all local variables at declaration: `int count = 0;`, `char *p = NULL;`. 3. For structs, use `= {0}` to zero-initialize: `struct Foo f = {0};`.
+- **Tool sequence**: shell_exec (`gcc -Wall -Wuninitialized`) → file_read (variable declaration) → file_edit (add initializer)
+- **Pitfall**: Do NOT rely on global/static variables being zero-initialized to justify skipping local initialization. Be explicit.
+
+## Verification
+Compile command: `gcc -Wall -Wextra -Werror -g -fsanitize=address,undefined -o program main.c`
+- Fix all warnings before proceeding — `-Werror` enforces this.
+- Run Valgrind for memory checks in CI: `valgrind --error-exitcode=1 ./program`
+
+## Validation Checklist
+- [ ] `gcc -Wall -Wextra -Werror` produces zero warnings
+- [ ] Every `malloc`/`calloc`/`realloc` return value checked for NULL
+- [ ] Every `free` followed by setting pointer to NULL
+- [ ] No `gets`, `strcpy`, or unbounded `sprintf` in codebase
+- [ ] All local variables initialized at declaration
+- [ ] No signed integer arithmetic that can overflow without a guard
+- [ ] All functions declared before first use (via include or forward declaration)
+- [ ] Tested with `-fsanitize=address,undefined` during development

package/dist/skills/skills/languages/cpp.md

@@ -0,0 +1,75 @@
+## Identity
+- domain: cpp
+- type: language
+- confidence: 0.93
+
+# C++ — Error Pattern Reference
+
+Compile with `-Wall -Wextra -Werror -std=c++17` (or `c++20`). Use sanitizers (`-fsanitize=address,undefined`) and run under Valgrind. Prefer RAII and smart pointers to manual memory management.
+
+## Compiler Warning Quick Reference
+- **-Wdelete-non-virtual-dtor** — Deleting through base pointer without virtual destructor.
+- **-Wunused-variable / -Wunused-parameter** — Declared but never used.
+- **-Wreorder** — Member initializer order does not match declaration order.
+- **-Wshadow** — Local variable shadows outer scope variable.
+- **-Wreturn-type** — Non-void function missing return.
+- **-Wnull-dereference** — Pointer that may be null is dereferenced.
+
+## Known Error Patterns
+
+### Use-After-Free — Dangling Pointer
+- **Symptom**: ASan reports `heap-use-after-free`. Program crashes with random values or corrupt behavior.
+- **Cause**: A raw pointer is used after `delete` (or `delete[]`) has been called on it. Common after ownership transfer without setting the old pointer to `nullptr`, or returning a reference to a local variable.
+- **Strategy**: 1. Run with ASan: `g++ -fsanitize=address -g`. 2. Identify the delete and the subsequent access. 3. After deleting a raw pointer, set it to `nullptr`. 4. Prefer `std::unique_ptr` or `std::shared_ptr` — they prevent use-after-free by tying lifetime to scope. 5. Never return a reference or pointer to a local variable.
+- **Tool sequence**: shell_exec (`g++ -fsanitize=address -g && ./program`) → file_read (reported lines) → file_edit (replace raw pointer with smart pointer or add nullptr assignment)
+- **Pitfall**: Do NOT check `if (ptr != nullptr)` after use-after-free — once freed, the pointer is invalid even if not null.
+
+### Double Free
+- **Symptom**: ASan reports `double-free`. `glibc` detected "double free or corruption". Crash in heap management code.
+- **Cause**: `delete` or `free` called twice on the same pointer. Happens when multiple owners hold raw pointers to the same allocation, or a copy constructor/assignment is missing (Rule of Three/Five).
+- **Strategy**: 1. Grep for `delete` and `free` on the affected pointer. 2. Ensure only one owner calls delete. 3. Use `std::unique_ptr` to enforce single ownership. 4. If a class manages memory, implement the Rule of Five (destructor, copy ctor, copy assign, move ctor, move assign) or use `= delete` for copy.
+- **Tool sequence**: grep (`delete\|free`) → file_read (class definition) → file_edit (add Rule of Five or use smart pointer)
+- **Pitfall**: Setting pointer to `nullptr` after delete prevents double-free on the same pointer variable, but does NOT help if the pointer was copied first.
+
+### ODR Violation — Multiple Definitions
+- **Symptom**: Linker error: `multiple definition of 'foo'`; or subtle wrong-behavior bugs with no error (when violations occur across translation units with different definitions).
+- **Cause**: A function or non-inline variable defined (not just declared) in a header file that is included in multiple translation units. Or the same name defined twice in different `.cpp` files.
+- **Strategy**: 1. For functions defined in headers, mark them `inline` or move the definition to a `.cpp` file. 2. For variables in headers, use `inline` variable (C++17): `inline int g_count = 0;` or declare `extern` in header and define in one `.cpp`. 3. For templates, definitions in headers are allowed and do not violate ODR as long as they are identical.
+- **Tool sequence**: grep (function/variable name across headers) → file_read → file_edit (add `inline` or move to .cpp)
+- **Pitfall**: Do NOT add `static` to a header function to suppress the linker error — this gives each TU its own copy, which is a different bug.
+
+### std::vector Iterator Invalidation
+- **Symptom**: Crash or undefined behavior after modifying a `std::vector` while iterating it. Sanitizers may report heap-use-after-free.
+- **Cause**: `push_back`, `insert`, `erase`, or `resize` may reallocate the vector's internal buffer, invalidating all iterators, references, and pointers into the vector. Continuing to use old iterators causes UB.
+- **Strategy**: 1. Identify any modification to the vector inside a loop that iterates it. 2. For `erase`: use the erase-remove idiom or capture the returned iterator: `it = vec.erase(it)`. 3. For `push_back` during iteration: collect new elements in a separate vector and append after the loop. 4. If indices are used instead of iterators, re-read the index from the start after mutation.
+- **Tool sequence**: grep (`push_back\|erase\|insert`) → file_read (enclosing loop) → file_edit (fix iteration pattern)
+- **Pitfall**: Do NOT cache `vec.end()` before a loop that modifies the vector — recompute it or use index-based iteration.
+
+### Template Instantiation Error
+- **Symptom**: Long compiler error message starting with "note: required from here" with a chain of template instantiations. The actual error is at the bottom of the chain.
+- **Cause**: A template is instantiated with a type that does not satisfy the template's requirements (missing method, wrong type, etc.). Concept violations (C++20) or SFINAE failures.
+- **Strategy**: 1. Read the error from the BOTTOM UP — the root cause is at the last "error:" line. 2. Identify the type being substituted. 3. Check what operations the template body performs on `T` and confirm the substituted type supports them. 4. In C++20, use concepts to get clearer error messages.
+- **Tool sequence**: file_read (full error output, bottom first) → grep (template definition) → file_read → file_edit (constrain template or fix calling type)
+- **Pitfall**: Do NOT add template specializations to paper over a type mismatch. Fix the type or add proper constraints.
+
+### Missing Virtual Destructor
+- **Symptom**: Valgrind reports memory leaks for derived class members. Objects deleted through base pointer only partially destroy the object.
+- **Cause**: A base class with virtual methods lacks a virtual destructor. Deleting a derived object through a base pointer calls only the base destructor, skipping derived class cleanup.
+- **Strategy**: 1. Grep all base classes (classes with virtual methods). 2. Check if they have `virtual ~ClassName() = default;` or a defined virtual destructor. 3. Add it if missing.
+- **Tool sequence**: grep (`virtual`) → file_read (class definitions) → file_edit (add `virtual ~ClassName() = default;`)
+- **Pitfall**: Do NOT make a class non-polymorphic just to avoid the destructor — if it has any virtual methods, it needs a virtual destructor.
+
+## Verification
+Compile: `g++ -std=c++17 -Wall -Wextra -Werror -g -fsanitize=address,undefined -o program *.cpp`
+- Run Valgrind in CI: `valgrind --error-exitcode=1 --leak-check=full ./program`
+- For large projects: integrate with `clang-tidy` and `cppcheck`.
+
+## Validation Checklist
+- [ ] All base classes with virtual methods have a virtual destructor
+- [ ] No raw `new`/`delete` — prefer `std::make_unique`/`std::make_shared`
+- [ ] No iterator or pointer used after vector/container modification
+- [ ] No function or variable defined (not declared) in a header without `inline`
+- [ ] Rule of Five implemented for any class that manages a resource
+- [ ] Template errors read from bottom up before attempting a fix
+- [ ] `-fsanitize=address,undefined` run during development
+- [ ] No dangling references returned from functions (local variable reference)