@yuaone/core 0.8.4 → 0.9.0

package/dist/skills/skills/languages/swift.md

@@ -0,0 +1,74 @@
+## Identity
+- domain: swift
+- type: language
+- confidence: 0.95
+
+# Swift — Error Pattern Reference
+
+Read the full Xcode error and the associated `note:` context. Swift's compiler is strict but its error messages are detailed — the fix is usually contained in the output.
+
+## Error Code Quick Reference
+- **Fatal error: Unexpectedly found nil while unwrapping an Optional value** — force unwrap `!` on nil.
+- **Value of optional type 'X?' must be unwrapped** — optional used where non-optional expected.
+- **Type 'X' does not conform to protocol 'Y'** — missing protocol requirement.
+- **Sendable warning** — non-Sendable type crossing actor/concurrency boundary.
+- **Expression is 'async' but is not marked with 'await'** — async call without await.
+- **Call to main actor-isolated method in synchronous context** — @MainActor violation.
+- **Capture of 'x' with non-sendable type** — Swift 6 strict concurrency violation.
+- **Retain cycle** — strong reference cycle causing memory leak (detected in Instruments).
+
+## Known Error Patterns
+
+### Pattern: force unwrap crash (! on nil Optional)
+
+- **symptom**: `Fatal error: Unexpectedly found nil while unwrapping an Optional value` at a line with `!`
+- **cause**: The `!` force-unwrap operator is used on an `Optional` that is `nil` at runtime. Common sources: IBOutlet not connected, storyboard/nib loading timing, JSON parsing, optional chaining bypassed, `as!` cast failure.
+- **strategy**: 1. Find every `!` at or near the crashing line. 2. Replace force unwrap with safe alternatives: `if let x = optional { }`, `guard let x = optional else { return }`, or `optional ?? defaultValue`. 3. For `as!` casts, use `as?` with a guard: `guard let view = obj as? UIView else { return }`. 4. For IBOutlets, verify the outlet is connected in the storyboard (open IB, check the connection inspector). 5. Use `XCTUnwrap` in tests instead of `!`.
+- **toolSequence**: file_read (crashing line + surrounding context) → grep (`!` usage near the line) → file_edit (replace `!` with guard let or if let)
+- **pitfall**: Do NOT replace `!` with `?` and silently ignore nil — use `guard let` to fail explicitly with context when nil is unexpected.
+
+### Pattern: protocol conformance missing
+
+- **symptom**: `Type 'MyClass' does not conform to protocol 'Equatable'` (or `Codable`, `Hashable`, `Identifiable`, etc.)
+- **cause**: A type used in a context requiring a protocol does not implement all required methods/properties. Common for `Equatable` (needs `==`), `Hashable` (needs `hash(into:)`), `Codable` (needs `encode`/`init(from:)` for non-synthesizable types).
+- **strategy**: 1. Read the protocol requirement in the error. 2. For `Equatable`/`Hashable`/`Codable` with simple stored properties, add the protocol to the declaration — Swift synthesizes conformance automatically if all properties conform. 3. For types with custom logic or non-conforming properties, implement the required methods manually. 4. For `Identifiable`, add `var id: SomeHashable { }` property. 5. Use an extension to add conformance cleanly.
+- **toolSequence**: grep (protocol name + requirements) → file_read (type definition) → file_edit (add protocol conformance or implement requirements)
+- **pitfall**: Do NOT add `@unchecked Sendable` to dismiss protocol warnings without verifying thread safety manually.
+
+### Pattern: Sendable warning (concurrency)
+
+- **symptom**: `Sending 'x' risks causing data races` or `Type 'Foo' does not conform to 'Sendable'` — Swift 6 strict concurrency or Xcode 15+ warnings
+- **cause**: A value of non-Sendable type is passed across actor boundaries (e.g., from background Task to @MainActor). Swift's concurrency model requires types crossing isolation boundaries to be Sendable (value types or thread-safe classes).
+- **strategy**: 1. Identify the type causing the warning. 2. If it is a struct with value-type properties, it is automatically Sendable — no action needed (compiler should infer). 3. If it is a class, make it `final` and ensure all mutable state is protected by a lock or actor, then add `Sendable` conformance. 4. Use `@MainActor` on types that should always run on main thread. 5. For data flowing into async tasks, capture immutable copies: `let snapshot = mutableData` before the `Task { }`. 6. As a last resort for third-party types, use `@unchecked Sendable` with a `// THREAD-SAFE: reason` comment.
+- **toolSequence**: file_read (type crossing boundary) → file_edit (make Sendable or capture immutable copy before Task)
+- **pitfall**: Do NOT use `@unchecked Sendable` without a comment proving thread safety — it suppresses the warning but not data races.
+
+### Pattern: memory retain cycle (weak/unowned)
+
+- **symptom**: Memory grows unboundedly; objects not released after dismissal. Instruments Leaks shows a cycle. Common in closures capturing `self`, delegates, and notification observers.
+- **cause**: Object A holds a strong reference to object B, which holds a strong reference back to A. ARC cannot release either. Common in: closure capturing `self` strongly, delegate properties not marked `weak`, NotificationCenter observers not removed, Timer targets.
+- **strategy**: 1. In closures that reference `self`, use `[weak self]` capture: `{ [weak self] in guard let self else { return } ... }`. 2. Delegate properties: declare as `weak var delegate: MyDelegate?`. 3. NotificationCenter: store the observer token and remove it in `deinit`. 4. Timer: use `[weak self]` in the timer block and invalidate in `deinit`. 5. Use `[unowned self]` only when the closure's lifetime is strictly shorter than `self` — prefer `weak` when in doubt.
+- **toolSequence**: grep (`self\.`) in closure bodies → file_read → file_edit (add `[weak self]` capture list)
+- **pitfall**: Do NOT use `unowned` as a performance optimization for convenience — if the assumption is wrong and `self` is nil when the closure runs, it is an immediate crash.
+
+### Pattern: @MainActor isolation error
+
+- **symptom**: `Call to main actor-isolated instance method 'updateUI()' in a synchronous nonisolated context` or `Expression is 'async' but is not marked with 'await'`
+- **cause**: A `@MainActor`-isolated method is called from a non-isolated context (background task, async function without actor annotation). Swift 5.7+ enforces actor isolation at compile time.
+- **strategy**: 1. Identify the caller context — is it inside a `Task`, `DispatchQueue.global()` block, or plain function? 2. Wrap the `@MainActor` call in `await MainActor.run { }` when inside an async context. 3. Mark the calling function `@MainActor` if it logically belongs to the main thread. 4. Use `Task { @MainActor in ... }` to dispatch UI work. 5. For legacy code with `DispatchQueue.main.async`, migrate to `Task { @MainActor in }` for consistency with Swift Concurrency.
+- **toolSequence**: file_read (calling function) → file_edit (add `await MainActor.run { }` or `@MainActor` annotation)
+- **pitfall**: Do NOT use `DispatchQueue.main.async` to bypass `@MainActor` errors in new code — it defeats Swift's compile-time isolation checks and can still cause data races.
+
+## Verification
+Run: `xcodebuild -scheme <scheme> build` or `swift build`
+- For warnings as errors: `xcodebuild -scheme <scheme> build SWIFT_TREAT_WARNINGS_AS_ERRORS=YES`
+- For tests: `xcodebuild test -scheme <scheme>`
+
+## Validation Checklist
+- [ ] No force unwrap `!` without a `// SAFE: reason` comment proving non-nil
+- [ ] All closures capturing `self` use `[weak self]` unless lifetime is provably shorter
+- [ ] Delegate properties declared as `weak var`
+- [ ] NotificationCenter observers removed in `deinit`
+- [ ] `@MainActor` isolation errors resolved with `await MainActor.run` or actor annotation
+- [ ] Sendable violations resolved without `@unchecked Sendable` unless thread safety is documented
+- [ ] `xcodebuild build` exits 0 with no errors

package/dist/skills/skills/languages/terraform.md

@@ -0,0 +1,80 @@
+## Identity
+- domain: terraform
+- type: language
+- confidence: 0.90
+
+# Terraform — Error Pattern Reference
+
+Read the full error message including the resource address and provider error detail. Terraform errors are often split across a plan error and an apply error — both matter.
+
+## Error Code Quick Reference
+- **"Error: Error acquiring the state lock"** — Another operation holds the state lock.
+- **"Error: Reference to undeclared resource"** — Resource name typo or not yet defined.
+- **"Error: Provider configuration not present"** — Provider block missing or alias mismatch.
+- **"Error: Unsupported argument"** — Attribute not valid for the resource type/version.
+- **"Error: Cycle"** — Circular dependency between resources.
+- **"Error: Invalid value for variable"** — Variable validation constraint failed.
+- **"Warning: Deprecated attribute"** — Attribute removed in newer provider version.
+- **"Error: Backend configuration changed"** — Backend config changed without `terraform init -reconfigure`.
+
+## Known Error Patterns
+
+### State Lock Timeout — Backend Locking
+- **Symptom**: `Error: Error acquiring the state lock` with a lock ID and holder info; plan/apply hangs indefinitely.
+- **Cause**: A previous `terraform apply` or `plan` was interrupted (Ctrl-C, CI timeout, crash) without releasing the state lock. The backend (S3+DynamoDB, GCS, Terraform Cloud) still holds the lock from the dead operation.
+- **Strategy**: 1. Read the error output fully — it includes the lock ID and the operation that holds it. 2. Verify that no legitimate Terraform operation is running (check CI jobs, team members). 3. If confirmed stale, force-unlock: `terraform force-unlock <LOCK_ID>`. 4. For DynamoDB-backed state, you can also delete the lock item directly via AWS Console as a last resort. 5. Prevent future stale locks: use CI jobs with proper timeout handling and signal trapping.
+- **Tool sequence**: shell_exec (`terraform force-unlock <ID>`) → shell_exec (`terraform plan` to verify state is clean)
+- **Pitfall**: Do NOT force-unlock while another legitimate apply is running — you will corrupt the state. Confirm no other operations are active first.
+
+### Plan/Apply Diff Surprise — lifecycle ignore_changes
+- **Symptom**: `terraform plan` shows unexpected changes to a resource that was not modified in code; resource would be destroyed and recreated on every apply.
+- **Cause**: External systems (autoscalers, deployment tools, human edits) modified attributes that Terraform tracks. Without `lifecycle { ignore_changes = [...] }`, Terraform wants to revert these changes. Alternatively, a `for_each` or `count` index change can cause full resource replacement.
+- **Strategy**: 1. Run `terraform plan -out=tfplan` and read the diff carefully — identify which attribute is changing. 2. If the attribute is legitimately managed externally (e.g., `desired_count` on an ECS service managed by an autoscaler), add `lifecycle { ignore_changes = [desired_count] }`. 3. If it is a `for_each` index issue, check that the map keys are stable identifiers, not positional indices. 4. Never use `ignore_changes = all` — it makes Terraform blind to all drift.
+- **Tool sequence**: shell_exec (`terraform plan`) → file_read (resource definition) → file_edit (add lifecycle ignore_changes for specific attributes)
+- **Pitfall**: Do NOT add `ignore_changes` reflexively to stop a noisy plan — understand WHY the attribute is drifting and fix the root cause if it is your code making the unintended change.
+
+### Provider Version Constraint Missing — Breaking Changes
+- **Symptom**: `terraform init` installs a newer provider version that removes or renames attributes; existing configurations break after `terraform init -upgrade`.
+- **Cause**: `required_providers` block either has no version constraint or uses `~>` incorrectly, allowing major version upgrades that introduce breaking changes.
+- **Strategy**: 1. Read the `required_providers` block in `versions.tf` or the root module. 2. Pin to a compatible version range: `version = "~> 5.0"` (allows 5.x but not 6.0). 3. Review provider changelogs when intentionally upgrading. 4. Commit the `.terraform.lock.hcl` file to version control — it pins exact provider versions for reproducible builds. 5. Use `terraform providers lock` to regenerate the lock file after intentional upgrades.
+- **Tool sequence**: file_read (versions.tf) → file_edit (add or tighten version constraints) → shell_exec (`terraform init`) → shell_exec (git add .terraform.lock.hcl)
+- **Pitfall**: Do NOT delete `.terraform.lock.hcl` to "fix" provider issues — it is a security and reproducibility artifact. Regenerate it properly with `terraform providers lock`.
+
+### Sensitive Value in Output — Secret Exposure
+- **Symptom**: `terraform output` prints database passwords, API keys, or private keys in plaintext; CI logs expose secrets; state file contains secrets in plaintext.
+- **Cause**: An `output` block exposes a sensitive resource attribute (e.g., `aws_db_instance.password`, `tls_private_key.private_key_pem`) without `sensitive = true`. Even with `sensitive = true`, the value is still stored in plaintext in the Terraform state file.
+- **Strategy**: 1. Grep all `output` blocks for sensitive attributes. 2. Add `sensitive = true` to outputs that expose secrets — this prevents them from printing in logs. 3. Audit the state backend: ensure state storage (S3 bucket, GCS bucket) has encryption at rest and access logging enabled. 4. For truly sensitive values, use a secrets manager (AWS Secrets Manager, HashiCorp Vault) instead of outputting them via Terraform. 5. Never commit state files to version control.
+- **Tool sequence**: grep (`output "`) → file_read → file_edit (add sensitive = true) → shell_exec (verify state backend encryption config)
+- **Pitfall**: Do NOT think `sensitive = true` removes the secret from state — it only hides it in plan/apply output. The state file still contains it in plaintext.
+
+### Circular Dependency Between Resources
+- **Symptom**: `Error: Cycle: <resource_a> → <resource_b> → <resource_a>`; Terraform cannot determine apply order.
+- **Cause**: Resource A references an attribute of Resource B (creating A→B dependency), and Resource B references an attribute of Resource A (creating B→A dependency). This can happen through `depends_on`, data source references, or implicit attribute references.
+- **Strategy**: 1. Read the error — Terraform prints the full cycle chain. 2. Map out WHY each reference exists. 3. Break the cycle by: (a) extracting a shared resource that both depend on, (b) using a `null_resource` or `terraform_data` with `triggers` to decouple, (c) restructuring so one resource passes a value that does not itself depend on the other. 4. Avoid using `depends_on` on entire modules — use it only on specific resources.
+- **Tool sequence**: file_read (both resource definitions) → grep (cross-references between them) → file_edit (extract shared resource or remove circular reference)
+- **Pitfall**: Do NOT use `depends_on = []` to remove declared dependencies without understanding what ordering those dependencies enforced — you may create race conditions in provisioning.
+
+### Resource Replaced on Rename — State Orphan
+- **Symptom**: `terraform plan` shows a resource being destroyed and a new one created when you only renamed it in code; infrastructure is unnecessarily replaced.
+- **Cause**: Terraform tracks resources by their address (type + name). Renaming `aws_s3_bucket.old_name` to `aws_s3_bucket.new_name` looks like a deletion + creation.
+- **Strategy**: 1. Use `terraform state mv <old_address> <new_address>` to rename the resource in state without destroying it. 2. Then update the `.tf` file with the new name. 3. Run `terraform plan` — it should show no changes. 4. For module renames, use `terraform state mv module.old module.new`.
+- **Tool sequence**: shell_exec (`terraform state list`) → shell_exec (`terraform state mv <old> <new>`) → file_edit (rename in .tf) → shell_exec (`terraform plan`)
+- **Pitfall**: Do NOT apply before running `terraform state mv` — the apply will destroy existing infrastructure to "create" the renamed resource.
+
+## Verification
+Run: `terraform validate` then `terraform plan`
+- `terraform validate` must exit 0 with "Success! The configuration is valid."
+- `terraform plan` should show only the expected changes — read every `+`, `-`, and `~` carefully.
+- Run `tflint` for additional style and provider-specific checks.
+
+## Validation Checklist
+- [ ] `required_providers` has version constraints for all providers
+- [ ] `.terraform.lock.hcl` is committed to version control
+- [ ] All sensitive outputs have `sensitive = true`
+- [ ] No secrets stored in `.tfvars` files committed to version control
+- [ ] State backend uses encrypted storage with access logging
+- [ ] `terraform validate` exits 0
+- [ ] No `depends_on = [<entire_module>]` without justification
+- [ ] All `lifecycle` blocks are justified with a comment explaining why
+- [ ] Resource names use stable identifiers (not positional indices) in `for_each`
+- [ ] `tflint` passes with no errors

package/dist/skills/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/skills/languages/verilog.md

@@ -0,0 +1,80 @@
+## Identity
+- domain: verilog
+- type: language
+- confidence: 0.88
+
+# Verilog/SystemVerilog — Error Pattern Reference
+
+Read the exact synthesis or simulation tool message including the file, line, and severity level. HDL errors split into simulation errors (behavioral bugs) and synthesis errors (hardware mapping failures) — both must be resolved separately.
+
+## Error Code Quick Reference
+- **"Multiple drivers on net 'x'"** — Wire driven from more than one always block or assignment.
+- **"Latch inferred for 'x'"** — Incomplete sensitivity list or missing else/default branch.
+- **"Sensitivity list may not be complete"** — Missing signal in always block sensitivity.
+- **"Width mismatch in assignment"** — Left and right side bit widths differ.
+- **"Undefined variable 'x'"** — Wire/reg not declared before use.
+- **"Non-blocking assignment in combinational logic"** — `<=` used in `always @(*)` block.
+- **"Blocking assignment in sequential logic"** — `=` used in `always @(posedge clk)` block.
+- **"Undeclared port in module instantiation"** — Port name not found in the module definition.
+
+## Known Error Patterns
+
+### Blocking vs Non-Blocking Assignment — always Block Confusion
+- **Symptom**: Simulation produces correct results but synthesis behavior differs; waveforms show immediate vs delayed value updates; Synopsys/Vivado warns about mixed assignment types.
+- **Cause**: In `always @(posedge clk)` (sequential/flip-flop) blocks, non-blocking assignments (`<=`) should be used — they model register behavior with all updates applied simultaneously at the end of the time step. In `always @(*)` (combinational) blocks, blocking assignments (`=`) should be used — they model wire behavior with immediate evaluation. Mixing them causes simulation-synthesis mismatch.
+- **Strategy**: 1. Grep all `always @(posedge` blocks and verify every assignment uses `<=`. 2. Grep all `always @(*)` blocks and verify every assignment uses `=`. 3. Never mix `=` and `<=` in the same `always` block. 4. For `always @(posedge clk or posedge rst)` reset blocks, use `<=` for both the reset assignment and the normal operation.
+- **Tool sequence**: grep (`always @(posedge`, `always @(*`, `always @\(`) → file_read → file_edit (fix assignment operators)
+- **Pitfall**: Do NOT use blocking assignments in sequential logic to "optimize" simulation speed — it causes race conditions in simulation and simulation-synthesis mismatch that only appears on real hardware.
+
+### Multiple Drivers on Wire — Synthesis Error
+- **Symptom**: `Error: Multiple drivers on net 'bus_data'`; tool refuses to synthesize; simulation shows X (unknown) values on the wire.
+- **Cause**: In Verilog, a `wire` can only have one driver. If two `always` blocks both assign to the same `wire` or `reg`, or if two module instantiations both drive the same net, the result is undefined. Common in bus architectures where multiple modules share a data bus.
+- **Strategy**: 1. Grep the signal name to find all assignment locations (`assign`, `always` blocks, module output ports). 2. For bus sharing, use a mux: only one driver is active at a time based on a select signal. 3. For tri-state buses, use `wire` with `assign bus = enable ? data : 1'bz`. 4. For `reg` types, ensure only one `always` block drives each register. 5. Use SystemVerilog `logic` type which provides better error detection for multiple drivers.
+- **Tool sequence**: grep (signal name across all files) → file_read → file_edit (add mux or tri-state logic, remove duplicate drivers)
+- **Pitfall**: Do NOT use `wire` with multiple `assign` statements hoping the synthesis tool will "figure it out" — multiple drivers on a wire is a hardware short circuit.
+
+### Latch Inferred — Incomplete Case or Missing Else
+- **Symptom**: Synthesis warning `Latch inferred for signal 'x' in process`; FPGA resource usage shows unexpected latches instead of flip-flops; behavior differs between simulation and synthesis.
+- **Cause**: In combinational `always @(*)` blocks, if not all possible input combinations assign a value to an output, the synthesizer infers a latch to "hold" the previous value. This happens with: incomplete `if-else` (missing `else`), incomplete `case` (missing `default`), or a signal only assigned in some branches.
+- **Strategy**: 1. Grep all `always @(*)` blocks. 2. For every `if` statement, ensure there is a matching `else` that assigns all outputs. 3. For every `case` statement, ensure there is a `default` branch that assigns all outputs. 4. As a defensive pattern, assign default values to all outputs at the top of the combinational block before the `if`/`case`, then override in branches. 5. If a latch is intentionally needed, use a `reg` in a sequential block instead.
+- **Tool sequence**: grep (`always @(\*)`) → file_read → file_edit (add default assignments at top or add else/default branch)
+- **Pitfall**: Do NOT suppress latch inference warnings — latches are timing hazards and usually indicate a bug. Investigate every latch warning.
+
+### Clock Domain Crossing Metastability
+- **Symptom**: Intermittent failures only on actual FPGA hardware; simulation passes; timing analysis shows paths crossing clock domains; MTBF (mean time between failures) calculation fails.
+- **Cause**: Signals passing from one clock domain to another can arrive at a flip-flop near its setup/hold time window. The flip-flop enters a metastable state that randomly resolves to 0 or 1. A single flip-flop synchronizer does not provide sufficient metastability resolution time.
+- **Strategy**: 1. Identify all signals that cross clock domains — look for signals driven in one `always @(posedge clk_a)` block and read in another `always @(posedge clk_b)` block. 2. For single-bit signals, use a 2-flip-flop synchronizer: two cascaded FFs in the destination clock domain. 3. For multi-bit data, use a FIFO with separate read/write clock ports (Gray code counter or vendor-provided async FIFO). 4. For control signals, use handshake protocols (req/ack). 5. Use CDC analysis tools (Synopsys SpyGlass, Cadence JasperGold CDC).
+- **Tool sequence**: grep (signals used across multiple clock domains) → file_read → file_edit (add synchronizer FFs or async FIFO)
+- **Pitfall**: Do NOT use a simple `assign` to cross clock domains — even a single combinational wire crossing clock domains is a CDC violation that will cause intermittent failures.
+
+### Simulation vs Synthesis Mismatch — Initial Blocks and Delays
+- **Symptom**: Simulation shows correct behavior with `#delay` timing; synthesis produces incorrect functionality; `initial` block values don't reflect on FPGA startup.
+- **Cause**: (1) `#delay` timing constructs are ignored by synthesis tools — they are simulation-only. (2) `initial` blocks are not synthesizable in most target technologies (exception: FPGA block RAMs with initial values). (3) Simulation starts with `x` values which combine operations may mask; synthesis optimizes based on don't-care.
+- **Strategy**: 1. Grep all `#` delay statements — remove them from synthesizable RTL and document they are testbench-only constructs. 2. Grep all `initial` blocks — if they are in RTL (not testbench), replace register initialization with a reset signal. 3. Use synchronous reset `always @(posedge clk) if (rst) out <= 0;` instead of `initial begin out = 0; end`. 4. Maintain separate testbench files (`*_tb.v`) with clear naming to avoid mixing simulation and RTL constructs.
+- **Tool sequence**: grep (`#[0-9]`, `initial begin`) → file_read → file_edit (remove #delays, replace initial with reset logic)
+- **Pitfall**: Do NOT use `#1` delays in RTL to "fix" simulation race conditions — the correct fix is proper use of non-blocking assignments, not delays.
+
+### Width Mismatch — Truncation or Zero-Extension Bug
+- **Symptom**: Tool warns `Width mismatch: assigning 32-bit value to 8-bit net`; runtime shows truncated or zero-extended values; arithmetic produces unexpected results.
+- **Cause**: Verilog implicitly truncates or zero-extends values when widths don't match. Assigning a 32-bit result to an 8-bit register silently discards the upper 24 bits. Integer literals default to 32 bits.
+- **Strategy**: 1. Enable all synthesis and simulation warnings — treat width mismatch warnings as errors. 2. Explicitly size all literals: `8'd255` not `255`. 3. Use explicit width casts: `result[7:0]` to select specific bits. 4. For addition with carry, declare the result one bit wider than the operands: `wire [8:0] sum = {1'b0, a} + {1'b0, b}; wire carry = sum[8];`. 5. Use SystemVerilog `logic [N-1:0]` with explicit width declarations everywhere.
+- **Tool sequence**: file_read (signals and assignments) → file_edit (add explicit bit widths to literals and widen result registers)
+- **Pitfall**: Do NOT treat implicit truncation as intentional bit selection — use explicit `[N-1:0]` slice notation to document intent.
+
+## Verification
+Run simulation: `vvp a.out` (Icarus) or ModelSim `vsim`
+- All assertions must pass; waveform matches expected behavior.
+- Run synthesis: Vivado `synth_design` or Quartus — zero errors, zero latch warnings.
+- Run static timing analysis (STA) — all timing paths must meet constraints (WNS > 0).
+
+## Validation Checklist
+- [ ] All `always @(posedge clk)` blocks use non-blocking assignments (`<=`)
+- [ ] All `always @(*)` blocks use blocking assignments (`=`)
+- [ ] No `#delay` constructs in RTL (only in testbenches)
+- [ ] No `initial` blocks in synthesizable RTL (use reset logic instead)
+- [ ] All `case` statements have a `default` branch
+- [ ] All `if` statements have a matching `else` branch (or default assignment at block top)
+- [ ] No multiple drivers on any single net
+- [ ] All CDC paths use 2-FF synchronizers or async FIFOs
+- [ ] All signal widths explicitly declared — no implicit width mismatches
+- [ ] Synthesis timing analysis passes with positive WNS on all critical paths

package/dist/skills/skills/languages/vue.md

@@ -0,0 +1,73 @@
+## Identity
+- domain: vue
+- type: language
+- confidence: 0.92
+
+# Vue.js — Error Pattern Reference
+
+Read the full Vue warning in the browser console. Vue warnings include the component name and the exact issue. Options API and Composition API have different error patterns — identify which is in use first.
+
+## Quick Reference
+- **[Vue warn]: Property or method "x" is not defined** — Options API scope issue.
+- **[Vue warn]: Missing required prop** — Parent did not pass a required prop.
+- **[Vue warn]: Extraneous non-emits event listeners** — Event name mismatch between `$emit` and `emits`.
+- **[Vue warn]: Component emitted event "x" but it is not declared** — Add to `emits` option.
+- **[Vue warn]: Failed to mount component** — Template or render error during initial mount.
+
+## Known Error Patterns
+
+### Property or Method Not Defined on Instance
+- **Symptom**: `[Vue warn]: Property or method "foo" is not defined on the instance but referenced during render.`
+- **Cause**: In Options API, a property used in the template is not declared in `data()`, `computed`, `methods`, or `props`. Common causes: typo in property name, forgetting to add to `data()`, using a local variable instead of reactive data.
+- **Strategy**: 1. Read the component's `data()` function and `methods` object. 2. Verify the property name matches exactly (case-sensitive). 3. If the property should be reactive, add it to `data()` with an initial value. 4. If it is a computed value, add it to `computed`. 5. If it is read-only input, add it to `props`.
+- **Tool sequence**: file_read (component data/methods) → grep (property name in template) → file_edit (add to data or methods)
+- **Pitfall**: Do NOT add a property directly to `this` outside of `data()` (e.g., in `created`). Vue 2 cannot make it reactive retroactively; use `this.$set` or declare it in `data()` with an initial value.
+
+### Reactive Data Mutation — Direct Array Index Set
+- **Symptom**: Array is modified but the UI does not update. No Vue warning. `console.log` shows the correct value.
+- **Cause**: In Vue 2, direct index assignment (`this.items[0] = newValue`) and `length` mutation are not reactive. Vue 2's reactivity cannot track these. In Vue 3, `reactive()` arrays do support index assignment, but replacing a `ref`'d array element requires reassignment.
+- **Strategy**: Vue 2: Use `this.$set(this.items, 0, newValue)` or `this.items.splice(0, 1, newValue)`. Vue 3 with `reactive`: direct assignment works. Vue 3 with `ref`: replace the whole array `items.value = [...items.value.slice(0, 0), newValue, ...items.value.slice(1)]` or use splice on `items.value`.
+- **Tool sequence**: file_read (mutation code) → file_edit (replace index assignment with $set/splice or reassignment)
+- **Pitfall**: Do NOT use `Vue.set` in Vue 3 — it does not exist. Only needed in Vue 2.
+
+### v-for Without :key
+- **Symptom**: `[Vue warn]: Elements in iteration expect to have a 'v-key' directive`. List re-renders incorrectly: items swap, animations are wrong, component state is misattributed.
+- **Cause**: `v-for` without a unique `:key` forces Vue to use positional diffing, which is incorrect when the list can be reordered, filtered, or have items added/removed.
+- **Strategy**: 1. Add `:key` to every `v-for` element with a stable, unique identifier from the data (e.g., `:key="item.id"`). 2. Do NOT use the loop index as key when items can be reordered or deleted. 3. Use index as key only for truly static lists that never change order.
+- **Tool sequence**: grep (`v-for`) → file_read (template) → file_edit (add `:key="item.id"`)
+- **Pitfall**: Do NOT use `Math.random()` as a key — it regenerates on every render, destroying component state.
+
+### Composition API Reactive Destructure Loss
+- **Symptom**: Destructured value from `reactive()` is not reactive — does not update when the original object changes.
+- **Cause**: `const { foo } = reactive({ foo: 1 })` creates a plain (non-reactive) copy of the value. Reactivity requires keeping the reference to the reactive object.
+- **Strategy**: 1. Use `toRefs()` to preserve reactivity when destructuring: `const { foo } = toRefs(state)`. Then access as `foo.value`. 2. Alternatively, do not destructure — access as `state.foo` throughout. 3. For Composable return values, always return `toRefs(state)` or individual `ref`s so callers can destructure safely.
+- **Tool sequence**: grep (`reactive`) → file_read (destructure site) → file_edit (wrap in `toRefs` or access via object)
+- **Pitfall**: `toRef(state, 'foo')` creates a single ref linked to one property. Use `toRefs(state)` to convert the whole object.
+
+### async setup Without Suspense
+- **Symptom**: Component renders blank or throws. Parent shows no loading state. Vue warning: `async setup() is used without a parent <Suspense>`.
+- **Cause**: In Vue 3, a component with `async setup()` (or `await` at the top level of `<script setup>`) must be wrapped by a `<Suspense>` component. Without it, async setup is not awaited before render.
+- **Strategy**: 1. Wrap the async component with `<Suspense>` in the parent: `<Suspense><AsyncComponent /></Suspense>`. 2. Provide a `#fallback` slot for the loading state. 3. If Suspense is not suitable, move async data fetching to `onMounted` and manage loading state with a `ref<boolean>`.
+- **Tool sequence**: file_read (async component) → file_read (parent template) → file_edit (add Suspense wrapper or move await to onMounted)
+- **Pitfall**: Do NOT silence the warning by removing `async` from `setup` — this breaks the `await`. Fix by adding Suspense or refactoring to `onMounted`.
+
+### Watchers Not Triggering on Nested Object Change
+- **Symptom**: `watch` callback does not fire when a nested property of a reactive object changes.
+- **Cause**: By default, `watch` in Vue 3 is not deep. It only detects top-level reference changes. Mutating a nested property does not trigger the watcher.
+- **Strategy**: 1. Add `{ deep: true }` to the watch options: `watch(state, callback, { deep: true })`. 2. Alternatively, watch the specific nested property: `watch(() => state.nested.value, callback)`. 3. The targeted approach (option 2) is preferred for performance.
+- **Tool sequence**: file_read (watch definition) → file_edit (add `{ deep: true }` or narrow watch target)
+- **Pitfall**: `{ deep: true }` traverses the entire object tree on every change. Use targeted watches for deeply nested or large objects.
+
+## Verification
+Run: `vue-tsc --noEmit` (if using TypeScript with Vue), or `vite build` for full compilation.
+- Browser console must show zero `[Vue warn]` messages in development.
+
+## Validation Checklist
+- [ ] All `v-for` elements have `:key` bound to a stable unique ID (not index for dynamic lists)
+- [ ] All reactive data mutations use Vue-compatible methods (not index assignment in Vue 2)
+- [ ] All `reactive()` destructures use `toRefs()`
+- [ ] All `async setup()` components are wrapped in `<Suspense>`
+- [ ] Vue console shows zero `[Vue warn]` messages in development build
+- [ ] Watchers on nested object properties use `{ deep: true }` or targeted arrow function
+- [ ] `emits` option declared for all events emitted by the component
+- [ ] `props` declared with types and required flag for all parent-to-child data

package/dist/skills/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/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/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