@raishin/vanguard-frontier-agentic 3.0.2 → 3.1.1

package/skills/frontend/typescript-contracts-review/metadata.json

@@ -0,0 +1,29 @@
+{
+  "id": "typescript-contracts-review",
+  "name": "TypeScript Contracts Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Reviews tsconfig strictness posture, any/assertion usage at trust boundaries, and exported public-API type surfaces so type signatures are enforced runtime-shape guarantees rather than decorative annotations, requiring paired runtime validation wherever external data enters the type system.",
+  "source_type": "original",
+  "official_docs": [
+    "https://www.typescriptlang.org/tsconfig",
+    "https://www.typescriptlang.org/docs/handbook/2/basic-types.html",
+    "https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-4.html",
+    "https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html",
+    "https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html",
+    "https://typescript-eslint.io/rules/"
+  ],
+  "security_notes": "Flag any, as, and non-null assertions (!) at trust boundaries (parsed JSON, third-party SDK responses, postMessage payloads, URL/query-param parsing) without paired runtime validation — a type annotation is erased at compile time and enforces nothing against a malformed or malicious payload. Flag @ts-ignore/@ts-expect-error without an adjacent justification comment, especially on security-relevant code. Flag any proposal to loosen tsconfig strictness (removing strict, disabling strictNullChecks) without an explicit, separately-reviewed migration plan.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/typescript-contracts-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/typescript-contracts-review/references/public-api-surface-diff.md

@@ -0,0 +1,59 @@
+# Public API Surface Diffing
+
+Use this reference when a diff touches an exported/published package (a library consumed by other packages or external users via its declared entry points and generated `.d.ts` files) and a breaking-change check against the previous public type surface is needed.
+
+## What people get wrong
+
+The naive story is:
+
+> No runtime logic changed, only type signatures — so this can't be a breaking change.
+
+Wrong. TypeScript's declaration-file contract (`.d.ts`) *is* the public API surface for a published package's consumers. A change with zero runtime behavior difference can still be a semver-breaking change for anyone whose code type-checks against this package, because their build breaks even though the JavaScript that ships would have behaved identically.
+
+## Officially grounded shape
+
+Per the TypeScript declaration-files handbook, `.d.ts` files describe the shape of a library to consumers — they are the contract a downstream `tsc` run checks against, independent of the actual runtime implementation. Consequences that matter for a breaking-change review:
+
+- **Removing an export** (a function, type, interface, class, or re-export) breaks every consumer importing it, even if nothing else changed.
+- **Narrowing a parameter type** (accepting fewer input shapes than before, e.g. `string` → `'a' | 'b'`) breaks consumers who were legitimately passing a now-disallowed value, even if that value never caused a runtime error.
+- **Widening a publicly-returned type in a way that removes previously-guaranteed members** (e.g. a return type that used to always include `id: string` now types it as `id?: string`, or a return type widens from a specific union to a broader one) breaks consumers whose downstream code relied on the narrower guarantee, even though the runtime object may not have changed at all.
+- **Adding a required property to an exported interface/type** that consumers are expected to construct (not just consume) breaks every call site constructing that type without the new property.
+- **Changing a type from an interface to a type alias (or vice versa)** is usually safe for consumption but can break consumers who were declaration-merging against the interface — a real but narrower risk to check when the package is designed for extension.
+- **Generic parameter changes** (adding a required type parameter, changing a default, changing variance-relevant usage) can break consumers who don't explicitly specify type arguments and were relying on inference.
+
+## Non-negotiable design rules
+
+1. **Diff the emitted public surface, not just the source diff.** The source diff shows what changed in the implementation file; the question that matters is what changed in what the package actually exports from its declared entry point(s) (per `package.json` `exports`/`types`/`main` fields). An internal type change that never reaches an exported symbol is not a public API break.
+2. **Type-only changes are real changes.** Do not wave through a diff as "just types, no behavior change" — for a published package, a type-only change to an exported symbol is exactly the kind of change semver-breaking-change review exists for.
+3. **Distinguish parameter-position from return-position changes** — narrowing accepted input is breaking; narrowing *offered* output guarantees is also breaking, but for a different reason (consumers relying on the wider prior contract). Both directions matter; do not only check one.
+4. **Check re-exports, not just direct declarations.** A type re-exported from a barrel file (`export * from './internal'`) is part of the public surface exactly as much as a type declared at the entry point — a change to the underlying `./internal` type is a public break even if the entry-point file itself has no diff.
+5. **A change behind an internal-only export or a `@internal`/unexported symbol is not a public break** — confirm the changed symbol is actually reachable from the package's declared public entry point(s) before flagging it as breaking; do not over-flag purely-internal refactors.
+
+## Minimal safe audit flow
+
+1. Identify the package's declared public entry point(s) from `package.json` (`main`, `module`, `types`/`typings`, or the `exports` map's `types` conditions for each subpath).
+2. From the diff, list every exported symbol (function, class, interface, type alias, enum, const) whose declaration changed, was added, or was removed — including via re-export chains reachable from the entry point(s).
+3. For each changed exported symbol, classify the change: added (usually safe), removed (breaking), parameter narrowed (breaking for callers), parameter widened (usually safe), return narrowed/property-removed-or-optionalized (breaking for consumers), return widened purely additively (usually safe).
+4. For anything classified breaking, state the concrete failure mode for a consumer: what specific call pattern that currently type-checks against the published types would fail to type-check against the new ones.
+5. If the repo has no automated API-surface-diff tooling in place (e.g. no `api-extractor`, no `.d.ts`-snapshot test), note that as a process gap rather than silently accepting the manual audit as a full substitute for automated coverage on every future change.
+
+## High-risk assumptions to kill
+
+- "No runtime behavior changed, so it's not breaking" — irrelevant for a published package's type contract.
+- "This is just a refactor, the public API is the same" — verify against the actual entry-point re-export chain; an internal rename can accidentally change what a barrel file re-exports.
+- "Adding a property to an interface is always additive/safe" — true for consumption (reading), false for construction (a consumer building an object literal to satisfy that interface now needs the new property too, unless it was added as optional).
+- "TypeScript would catch this for us automatically" — it catches it for *this repo's own* compile, not for downstream consumers' separate compiles against the published `.d.ts`; the break only surfaces in their build, after the package is published.
+
+## Verification targets
+
+- `package.json` `exports`/`types`/`main` fields, to establish the actual public entry point(s).
+- `git diff` scoped to files reachable from those entry points (direct declarations and re-export chains).
+- If available, a generated `.d.ts` diff (build output before/after) or an `api-extractor`-style report — prefer this over manual source-diff reasoning when the tooling exists, since re-export chains and inferred types are easy to miscount by hand.
+
+## When to push back
+
+Push back if the user asks to:
+
+- ship a narrowed parameter type or removed export as a patch/minor version bump without flagging it as a breaking (major) change,
+- describe a type-only breaking change as "not a real change" because runtime behavior is unaffected,
+- skip the public-surface check because "it's just an internal refactor" without first confirming the changed symbol isn't reachable from a declared entry point.

package/skills/frontend/typescript-contracts-review/references/strict-flag-posture.md

@@ -0,0 +1,61 @@
+# Strict-Flag Posture
+
+Use this reference when auditing or recommending a tsconfig strict-family flag set, or when a reviewer needs to determine what a repo's `strict: true` actually enables on its installed compiler.
+
+## What people get wrong
+
+The naive story is:
+
+> The repo sets `"strict": true`, so it's using TypeScript's strictest checking.
+
+Incomplete, for two separate reasons:
+
+1. `strict` is a bundle, and the bundle's membership is **open-ended by design**. Per the TypeScript docs: turning `strict` on "is equivalent to enabling all of the strict mode family options... Future versions of TypeScript may introduce additional stricter checking under this flag." A repo pinned to an older `typescript` version gets a smaller bundle than the same `strict: true` on a newer one.
+2. Two of the most consequential type-soundness flags — `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` — are **not** part of the `strict` bundle at all. They are separate opt-in flags. A repo can be maximally "strict" by the `strict: true` definition and still have neither enabled.
+
+## Officially grounded shape (what the docs say)
+
+- `strict: true` is the master flag; it currently bundles at minimum `strictNullChecks`, `noImplicitAny`, `noImplicitThis`, `alwaysStrict`, `strictFunctionTypes`, `strictBindCallApply`, `strictPropertyInitialization`, and (since TypeScript 4.4) `useUnknownInCatchVariables`. Verify the current exact bundle via `query-docs` against the installed version — do not treat this list as closed or version-independent.
+- `useUnknownInCatchVariables` (TS 4.4+) changes the default type of a `catch` variable from `any` to `unknown`. It is auto-enabled under `strict`. Its presence means catch-block property access (`err.message`) requires narrowing first (e.g. `instanceof Error`) — code that skips narrowing under an older compiler target may newly fail, or may be silently unsound if the repo is still pre-4.4.
+- `noUncheckedIndexedAccess` — **not** in the `strict` bundle — makes indexed access (`arr[i]`, `record[key]`) include `undefined` in the result type. Without it, index signatures and array access lie: `arr[i]` types as `T`, not `T | undefined`, even though out-of-bounds access returns `undefined` at runtime.
+- `exactOptionalPropertyTypes` — **not** in the `strict` bundle — makes `{ prop?: string }` distinguish "prop is absent" from "prop is present and set to `undefined`". Without it, `obj.prop = undefined` is accepted as satisfying an optional property even where the author's intent required the key to be entirely absent (relevant for APIs that branch on `'prop' in obj` or `Object.keys`).
+- As of TypeScript 5.9, `tsc --init` generates both of these under a separate "Stricter Typechecking Options" block alongside `strict: true` — this is a **default-generation change**, not a retroactive change to what `strict` means. Repos scaffolded before 5.9 will not have picked these up automatically, and repos on TypeScript versions predating their introduction cannot have them regardless of `tsc --init` vintage.
+
+> Version note: exact strict-family bundle membership and default `tsc --init` output are version-sensitive. Confirm both via `query-docs` against the specific `typescript` version in the repo's lockfile before making a definitive claim — do not rely on a memorized flag list.
+
+## Non-negotiable design rules
+
+1. **Read the effective config, not just the top-level file.** `tsconfig.json` can `extends` a base config (monorepo shared config, `@tsconfig/*` package). A flag absent from the leaf file may be inherited, or a permissive leaf-level override may silently defeat a strict base. Resolve the full `extends` chain before concluding a flag is off.
+2. **Distinguish "not in `strict`" from "not needed."** `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` are the two flags most commonly mistaken for redundant with `strict`. Treat their absence as a real gap to call out, not a non-finding, whenever the diff under review does array/record indexing or optional-property assignment that would behave differently under them.
+3. **Version-gate every strict-bundle claim.** Do not assert "this repo has `useUnknownInCatchVariables`" from `strict: true` alone — confirm the installed `typescript` version is 4.4+ first.
+4. **Treat strictness removal as a migration, not a diff line.** A one-line change disabling `strictNullChecks` or removing `strict` can silently make thousands of previously-checked call sites unchecked. Require an explicit, separately-reviewed migration plan (with a scoped rollout, e.g. per-directory `strict` via TypeScript project references, or documented follow-up) rather than approving it inline in an unrelated feature PR.
+5. **Do not conflate ESLint strictness with compiler strictness.** `typescript-eslint`'s `strict-type-checked` config and the compiler's `strict` flag are independent axes — a repo can have one without the other. Check both when the review scope includes lint config.
+
+## Minimal safe audit flow
+
+1. Read `package.json`/lockfile to get the exact `typescript` version.
+2. Read `tsconfig.json` and resolve its full `extends` chain to the effective merged config.
+3. List which strict-family flags (per the version-confirmed bundle) are on, and separately whether `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` are on.
+4. Compare against current TypeScript-recommended defaults (via `query-docs`) for that version, and note the gap explicitly rather than treating "has `strict: true`" as sufficient.
+5. If the diff under review does indexed access or optional-property assignment and the relevant flag is off, name the specific unsound pattern this enables (e.g. "line 42 assumes `config[key]` is never `undefined`; with `noUncheckedIndexedAccess` off, the compiler will not catch this if `key` is absent from `config`").
+
+## High-risk assumptions to kill
+
+- "`strict: true` means fully strict" — it does not include `noUncheckedIndexedAccess` or `exactOptionalPropertyTypes`.
+- "The build passes, so the types are sound" — passes only prove soundness relative to whatever flags are actually active, which may be a materially weaker set than the reviewer assumes.
+- "Newer TypeScript version means newer defaults apply automatically" — `tsc --init` default generation only affects newly scaffolded configs; upgrading the compiler does not retroactively add opt-in flags to an existing `tsconfig.json`.
+- "This monorepo's shared base config is strict, so every package is strict" — a leaf `tsconfig.json` can override or narrow it; always resolve the effective chain.
+
+## Verification targets
+
+- `cat tsconfig.json` and every file in its `extends` chain.
+- `npm ls typescript` / lockfile entry for the resolved `typescript` version.
+- `tsc --showConfig` (if available in the environment) to print the fully resolved effective compiler options — prefer this over manually merging `extends` chains by hand when the tool is available.
+
+## When to push back
+
+Push back if the user asks to:
+
+- disable `strict` (or any of its family) as a quick fix to unblock a build, without a scoped migration plan,
+- treat a passing `tsc --noEmit` as proof of runtime safety for external-data handling — it is not; that is the trust-boundary concern in a separate reference,
+- skip checking `noUncheckedIndexedAccess`/`exactOptionalPropertyTypes` because "the repo has `strict: true`" — that claim alone does not cover those flags.

package/skills/frontend/typescript-contracts-review/references/trust-boundary-validation.md

@@ -0,0 +1,68 @@
+# Trust-Boundary Validation Patterns
+
+Use this reference when auditing external-data ingestion points — API responses, `JSON.parse`, `postMessage`, URL/query-param parsing, form input, environment variables — for whether a declared TypeScript type is actually backed by a runtime check.
+
+## What people get wrong
+
+The naive story is:
+
+> I typed the response as `User`, so `response.data` is a `User`.
+
+Wrong, and dangerously so. TypeScript types are fully erased at compile time — the emitted JavaScript contains no trace of the type annotation. A cast like `const user = response.data as User` or a generic call like `fetch<User>(url)` where the generic only annotates the return type performs **zero runtime work**. If the actual payload is malformed, missing a field, or actively malicious (an attacker-controlled API, a compromised third-party SDK, a crafted `postMessage`), the code proceeds as if it received a valid `User` and every downstream consumer inherits that false confidence.
+
+This is not a hypothetical edge case — it is the default behavior of `JSON.parse`, which is typed to return `any` specifically because the compiler cannot know the shape of arbitrary parsed JSON. Any annotation applied after that point (`JSON.parse(raw) as Shape`, or assigning the `any` result to a `Shape`-typed variable) is the developer asserting a guarantee the compiler cannot verify and runtime does not enforce.
+
+## Officially grounded shape
+
+- `JSON.parse` returns `any`. Assigning that `any` to a typed variable, or asserting it with `as`, produces no runtime check — `typescript-eslint`'s `no-unsafe-assignment`, `no-unsafe-member-access`, and `no-unsafe-return` rules specifically exist to flag this exact pattern (an `any` from `JSON.parse` flowing into a typed context) because it is common enough to warrant dedicated tooling.
+- `no-explicit-any` and the `no-unsafe-*` family are part of `recommended-type-checked` / `strict-type-checked` shared configs — if the diff introduces this pattern in a repo that has those configs active, it should already surface as a lint failure; if it does not surface, either the config isn't active on that file or the pattern is disguised (e.g. via an intermediate `unknown` cast chained through `as`).
+- A type assertion (`as T`) does not perform a structural check; it only suppresses the compiler's own inference. `T!` (non-null assertion) similarly performs no runtime check — it only silences the compiler's null/undefined narrowing.
+- The compiler-sound way to narrow an `unknown` or `any` value to a specific type is a **type guard function** (`function isUser(x: unknown): x is User`) that performs actual runtime property/shape checks, or a schema-validation library (e.g. Zod, io-ts, ArkType — verify current API via `query-docs`/official docs for whichever the repo already uses; do not introduce a new one without the user's decision) whose `.parse()`/`.safeParse()` throws or returns a discriminated result on shape mismatch.
+
+## Non-negotiable design rules
+
+1. **Every trust boundary needs a paired runtime check, not just a type annotation.** Trust boundaries include: HTTP/fetch response bodies, WebSocket messages, `postMessage` payloads, URL/query-string parsing, `localStorage`/`sessionStorage` reads, environment variables consumed at runtime, file uploads, and any third-party SDK callback whose payload originates outside this codebase's own type-checked code.
+2. **A cast is not a check.** `as T`, `<T>value`, and `!` all compile away. None of them are acceptable as the sole guarantee for external data. Flag them at trust boundaries even if the code "usually works" — the point is what happens on the malformed/adversarial input, not the happy path.
+3. **`unknown` is the correct type for genuinely-unvalidated external input**, not `any`. `unknown` forces every consumer to narrow before use; `any` opts the value (and everything derived from it) out of type checking entirely, often silently propagating far beyond the original ingestion point.
+4. **Validation must match the type it claims to back.** A partial validator (checks `id` and `name` exist but the type declares five required fields) is a false sense of security — flag a type/validator shape mismatch as a defect, not just validator absence.
+5. **Distinguish internal-boundary types from trust-boundary types.** Not every `any`/assertion in a codebase needs a schema validator — internal function calls between already-typechecked code do not cross a trust boundary. Scope the audit to data that originates outside this codebase's own compiled/typechecked surface.
+
+## Minimal safe audit flow
+
+1. Identify every point in the diff where external data enters: fetch/axios/SDK response handling, `JSON.parse` calls, `postMessage` listeners, `URLSearchParams`/`location.search` reads, `process.env`/`import.meta.env` reads used in logic (not just build-time constants), form-field extraction.
+2. For each, trace whether the value passes through a runtime validator (schema library, hand-written type guard with actual property checks) before being treated as its declared type, or whether a bare assertion/cast/generic-only-annotation is the only "check."
+3. Where a validator exists, confirm its declared shape matches the TypeScript type it's meant to back — a validator checking fewer fields than the type declares is a gap, not full coverage.
+4. Where no validator exists, name the concrete blast radius: what downstream code trusts this value's shape, and what happens if a field is missing/wrong-typed/malicious (e.g. `undefined.toUpperCase()` throwing, or a numeric field actually being an attacker-supplied string flowing into a template literal or SQL-adjacent context).
+
+## Adversarial checklist
+
+Before approving a trust-boundary type as sound, answer:
+
+- What is the actual runtime function/library call that validates this data, by name — not "it's typed as `User`"?
+- What happens if a required field is absent? Does the validator reject it, or does the type only claim it's required while runtime silently proceeds with `undefined`?
+- What happens if a field has the wrong primitive type (a string where a number is declared)? Coercion, rejection, or silent pass-through?
+- Is the validator's schema kept in sync with the TypeScript type by construction (e.g. `z.infer<typeof schema>` generates the type from the validator) or are they two independently hand-maintained declarations that can drift?
+- If this is a third-party SDK response, does the SDK's own published types (if any) constitute a runtime guarantee, or are they — like all TypeScript types — compile-time only and equally unenforced by the SDK itself?
+
+If these cannot be answered concretely, the trust-boundary claim is unverified — report it as a finding, not a pass.
+
+## High-risk assumptions to kill
+
+- "It's typed, so it's validated" — types are erased; only executed code validates.
+- "The SDK's TypeScript types mean the SDK enforces the shape" — a third-party SDK's `.d.ts` file is exactly as unenforced at runtime as first-party code's types.
+- "We control the API, so the response is always well-formed" — deploy skew (client ahead of/behind the API), a compromised or misconfigured upstream, or a partial outage returning an error body with a 200 status all violate this assumption in practice.
+- "`as unknown as T` is safer than `as T`" — it silences the double-assertion protection the compiler otherwise gives when the two types are structurally too different to be a plausible mistake; it typically appears specifically to bypass that protection, which is a stronger signal something is being forced through.
+
+## Verification targets
+
+- `git diff` or `Grep` for `JSON.parse(`, ` as `, and `!` immediately following a value derived from `fetch`, `axios`, `postMessage`, `URLSearchParams`, `process.env`, or a named SDK client.
+- Presence and shape of a schema-validation library call (`.parse(`, `.safeParse(`, or a hand-written `is`-suffixed type-guard function) between the raw external value and its first typed use.
+- If a schema library generates the TypeScript type (e.g. `z.infer<...>`), confirm the type in the diff is actually derived that way rather than hand-declared separately, which would let the two drift.
+
+## When to push back
+
+Push back if the user asks to:
+
+- add a type annotation to an external-data-handling function as the fix for a bug, without adding a runtime check — the type change alone does not prevent the bug's root cause,
+- suppress a `no-unsafe-assignment`/`no-explicit-any` lint finding at a trust boundary with an inline disable comment instead of adding validation,
+- treat "the SDK is typed" as sufficient justification to skip validating that SDK's response shape.

package/skills/frontend/visual-regression-storybook-review/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: visual-regression-storybook-review
+description: Reviews Storybook visual-testing setup -- test-runner wiring, Chromatic integration, and the a11y addon's axe-core gating -- to ensure visually-critical components have deterministic pixel-diff and accessibility coverage before merge, grounded in current Storybook docs.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: delivery
+---
+
+# Visual Regression (Storybook) Review
+
+## Purpose
+
+Storybook can run three different kinds of automated checks -- the generic `test-runner`, hosted Chromatic visual/interaction diffing, and the `a11y` addon's axe-core accessibility checks -- and teams frequently conflate them or wire only one when they need two. This skill reviews which checks are actually wired, whether they gate merge or are advisory-only, and whether visually-critical components and all theme variants are in scope, grounded in current, version-specific Storybook API behavior rather than remembered config shapes that may be stale across majors.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review or configure Storybook's `test-runner`, Chromatic, or `a11y` addon setup,
+- diagnose why a visual or accessibility regression shipped despite Storybook tests passing,
+- decide whether a check should run locally, in the test-runner, or via Chromatic,
+- audit whether dark mode/RTL/reduced-motion story variants have visual and a11y coverage.
+
+## Context7 Documentation Protocol
+
+Storybook's addon config shape (`preVisit`/`postVisit` hooks, `parameters.a11y.*`, `chromatic.config.json` fields) has changed across Storybook 8/9/10 and is documented, not folklore -- never assert a hook signature, parameter name, or default value from memory.
+
+1. Call `ToolSearch` with query `"context7"` (or `"select:mcp__Context7__resolve-library-id,mcp__Context7__query-docs"`) to load the Context7 tools if not already loaded in this session.
+2. Call `mcp__Context7__resolve-library-id` with library name `Storybook` to obtain the current Context7-compatible ID (`/storybookjs/storybook`); prefer the resolved ID over guessing.
+3. Call `mcp__Context7__query-docs` for the specific claim in question -- e.g. "test-runner preVisit postVisit hooks configuration", "a11y addon parameters.a11y.test values", "Chromatic config.json fields and CI wiring" -- before stating it as fact. Do this per review, not once from a prior session's memory.
+4. Prefer the official docs URLs in `official_docs` for primary normative statements (exact parameter names, exact config shape); use Context7 to ground and cross-check the claim before writing it into a finding.
+5. If Context7 is unavailable or returns no relevant match, fall back to the `official_docs` URLs and mark the claim `documentation-based (Context7 unavailable)` rather than presenting it as freshly verified.
+6. Never invent a config key, addon parameter, hook name, or axe-core rule ID that no queried source confirms.
+
+## Lean operating rules
+
+- Distinguish the three tools explicitly: `test-runner` (generic CI test harness, runs locally or in CI via Playwright-driven `preVisit`/`postVisit` hooks), Chromatic (hosted visual + interaction diffing with a reviewer UI and git-provider sync), and the `a11y` addon (axe-core checks configured through `parameters.a11y.*`) -- do not treat them as interchangeable or assume one subsumes the others.
+- Confirm whether `parameters.a11y.test` is set to `'error'` (fails the build on violations) rather than left unset or at `'todo'` (warns only) before crediting a project with enforced accessibility gating; `'off'` disables the check entirely except for manual panel review.
+- Require that visually-critical stories include dark mode, RTL, and `prefers-reduced-motion` variants in the checked set, not just the default light theme -- a diff/a11y suite that only ever renders the default theme systematically misses regressions in every other supported mode.
+- Verify the exact addon/config API shape (e.g., `preVisit`/`postVisit` hook signatures, `injectAxe`/`configureAxe`/`checkA11y` from `axe-playwright`, or `parameters.a11y.context`/`config`/`options`) against the installed Storybook major version before recommending a `.storybook/test-runner.ts` or `preview.ts` diff, since these shapes have changed across Storybook 8/9/10.
+- Recommend masking or mocking non-deterministic content (timestamps, animations, randomized data, live network responses) before recommending a looser pixel-diff tolerance -- widening tolerance first hides the actual source of visual noise rather than fixing it.
+- Treat the test-runner and Chromatic as complementary, not redundant: the test-runner can run custom assertions locally and in any CI, while Chromatic adds hosted visual/interaction diffing with reviewer approval and git sync; a project that has only one may still have a real coverage gap depending on what it needs.
+- Load the design-token-governance skill instead of this one when the root cause is a token/contrast issue rather than a Storybook wiring gap; load `wcag-22-accessibility-audit` when the question is about accessibility compliance strategy broader than what the `a11y` addon checks.
+
+## References
+
+Load these only when needed:
+
+- [Test-runner and Chromatic wiring](references/test-runner-and-chromatic-wiring.md) -- use when reviewing or configuring the `test-runner`'s `preVisit`/`postVisit` hooks, CI invocation, or Chromatic project setup and the distinction between the two.
+- [Accessibility addon gating](references/accessibility-addon-gating.md) -- use when reviewing or configuring the `a11y` addon's `parameters.a11y.test` gating behavior, axe-core rule configuration, or diagnosing why violations aren't failing CI.
+- [Theme and variant coverage](references/theme-and-variant-coverage.md) -- use when auditing whether dark mode, RTL, and reduced-motion story variants have visual/a11y coverage, or when non-deterministic content needs masking before diffing.
+
+## Response minimum
+
+Return, at minimum:
+
+- which of the three tools (test-runner/Chromatic/a11y addon) is in scope and whether it currently gates merge,
+- theme/variant coverage gap (dark mode, RTL, reduced-motion) if any,
+- evidence level and the Storybook major version the guidance targets,
+- proposed config diff (not applied),
+- security caveat on any Chromatic/Percy token or PII-bearing baseline reviewed.

package/skills/frontend/visual-regression-storybook-review/metadata.json

@@ -0,0 +1,27 @@
+{
+  "id": "visual-regression-storybook-review",
+  "name": "Visual Regression (Storybook) Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Reviews Storybook-based visual regression and accessibility gating (test-runner, a11y addon, Chromatic integration) to ensure visually-critical components have deterministic pixel-diff and axe-core coverage before merge.",
+  "source_type": "original",
+  "official_docs": [
+    "https://storybook.js.org/docs/writing-tests/visual-testing",
+    "https://storybook.js.org/docs/writing-tests/integrations/test-runner",
+    "https://storybook.js.org/docs/writing-tests/accessibility-testing",
+    "https://www.w3.org/TR/WCAG21/#contrast-minimum"
+  ],
+  "security_notes": "Chromatic/Percy project tokens used in CI must be scoped per-project secrets, not account-wide credentials, and never committed to `chromatic.config.json` or `.storybook/main.js`. Screenshot baselines must not capture real user PII from a staging environment seeded with production-like data.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/visual-regression-storybook-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/visual-regression-storybook-review/references/accessibility-addon-gating.md

@@ -0,0 +1,86 @@
+# Accessibility Addon (a11y) Gating
+
+Use this reference when reviewing or configuring the `a11y` addon's `parameters.a11y.test` gating behavior, axe-core rule configuration, or diagnosing why accessibility violations aren't failing CI despite the addon being installed. For test-runner/Chromatic wiring, see `test-runner-and-chromatic-wiring.md`. For dark mode/RTL/reduced-motion coverage of the stories being checked, see `theme-and-variant-coverage.md`.
+
+> Version note: `parameters.a11y.test` and the `initialGlobals`/`globals.a11y.manual` flag are current documented shapes; the addon's config surface has changed across Storybook majors (notably the move to `parameters.a11y.test` gating via the Vitest addon or test-runner). Verify the exact parameter names against the installed Storybook version via Context7 (`/storybookjs/storybook`) or the official docs before writing a config diff.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> The `a11y` addon is installed, so accessibility violations block merge.
+
+That is false by default. The addon being installed only means violations are visible in the Storybook UI's a11y panel during manual browsing. Whether a violation actually fails a build depends entirely on the `parameters.a11y.test` value, which is `undefined` (no enforced test behavior) unless explicitly set.
+
+## Officially grounded shape
+
+The accessibility addon is built on `axe-core`; its configuration options largely map to axe-core's own API surface:
+
+| Property | Default | Description |
+|---|---|---|
+| `parameters.a11y.context` | `'body'` | Context passed to `axe.run` -- which elements checks run against. |
+| `parameters.a11y.config` | (empty) | Configuration passed to `axe.configure()` -- most commonly used to enable/disable individual rules. |
+| `parameters.a11y.options` | `{}` | Options passed to `axe.run` -- can adjust which rulesets are checked. |
+| `parameters.a11y.test` | `undefined` | Determines test behavior when run with the Vitest addon or the test-runner. |
+| `globals.a11y.manual` | `undefined` | Set `true` to prevent a story from being automatically analyzed when visited. |
+
+`parameters.a11y.test` accepts exactly three documented values:
+
+- `'off'` -- do not run accessibility tests automatically (manual panel review is still possible).
+- `'todo'` -- run accessibility tests; violations surface as a **warning** in the Storybook UI, not a failing test.
+- `'error'` -- run accessibility tests; violations surface as a **failing test** in the Storybook UI and CLI/CI.
+
+This parameter can be set at the project level (`.storybook/preview.ts`), the component level (a story file's meta/default export), or an individual story level -- so a project can have global `'error'` gating with a deliberate `'todo'` or `'off'` override on a specific known-noisy story, or the reverse (global `'todo'` with `'error'` only on a few critical components). Either shape is valid; the review's job is to confirm which shape actually exists and whether it matches intent.
+
+For test-runner-based enforcement (as opposed to the Vitest addon), the documented pattern injects and configures axe via the `axe-playwright` package inside the `preVisit`/`postVisit` hooks:
+
+```typescript
+import type { TestRunnerConfig } from '@storybook/test-runner';
+import { getStoryContext } from '@storybook/test-runner';
+import { injectAxe, checkA11y, configureAxe } from 'axe-playwright';
+
+const config: TestRunnerConfig = {
+  async preVisit(page) {
+    await injectAxe(page);
+  },
+  async postVisit(page, context) {
+    const storyContext = await getStoryContext(page, context);
+    await configureAxe(page, {
+      rules: storyContext.parameters?.a11y?.config?.rules,
+    });
+    const element = storyContext.parameters?.a11y?.element ?? 'body';
+    await checkA11y(page, element, {
+      detailedReport: true,
+      detailedReportOptions: { html: true },
+    });
+  },
+};
+export default config;
+```
+
+Note this is a distinct enforcement path from `parameters.a11y.test` (which governs the addon's own Vitest-addon/test-runner-integrated behavior) -- a project wiring axe manually through `axe-playwright` in `preVisit`/`postVisit` is not automatically respecting `parameters.a11y.test`, and the two should not be assumed to be reading the same configuration unless the `postVisit` hook explicitly reads `storyContext.parameters?.a11y?.config`.
+
+## Non-negotiable design rules
+
+1. **Never credit "a11y addon is installed" as accessibility gating without confirming `parameters.a11y.test` is `'error'`** (or that a manual `axe-playwright` wiring in `postVisit` calls `checkA11y` in a way that actually fails the test runner process, not just logs a report). `'todo'` and the addon's default unset state are advisory only.
+2. **Confirm which enforcement path is in use** -- `parameters.a11y.test` via the Vitest addon/test-runner integration, or a manually wired `axe-playwright` `preVisit`/`postVisit` pair -- before writing a config diff; they are configured differently and a fix aimed at the wrong path silently does nothing.
+3. **Do not recommend disabling a rule globally via `parameters.a11y.config.rules` to silence a violation** without first confirming the violation is a false positive for the actual DOM/ARIA semantics in question, not a real defect the team wants to suppress.
+4. **Respect `globals.a11y.manual: true` as an intentional opt-out signal**, not dead config -- confirm with the team whether a story marked `manual` is deliberately excluded (e.g., because it renders non-deterministic third-party content) before treating its absence from automated coverage as a gap to fix by removing the flag.
+5. **Scope `parameters.a11y.context` deliberately** when a story wraps content the team doesn't own (e.g., a third-party embed) -- running the full-page `axe.run` against unowned markup produces violations the team cannot fix and trains reviewers to ignore the panel.
+
+## Safe verification targets
+
+- `.storybook/preview.ts` -- confirm the project-level `parameters.a11y.test` value and any `initialGlobals.a11y.manual` default.
+- Individual story files -- confirm component/story-level `parameters.a11y` overrides match documented intent (not accidental inheritance).
+- `.storybook/test-runner.ts` -- if `axe-playwright` is used, confirm `preVisit` calls `injectAxe` and `postVisit` calls `checkA11y` with a real failure path (not a report-only call whose result is discarded).
+- CI logs from a Storybook build with a known-injected violation -- the most reliable evidence that gating is real is a CI run that actually failed on a deliberate violation, not just config inspection.
+
+## When to push back
+
+Push back if the user asks for:
+
+- treating `'todo'` as sufficient gating because "it shows up in the UI,"
+- disabling a specific axe rule project-wide to unblock a single component's merge, as a permanent fix rather than a scoped, justified exception,
+- adding the `a11y` addon without setting `parameters.a11y.test` anywhere, and calling that "accessibility testing is now covered."
+
+Visibility in a panel is not the same as a merge-blocking test.

package/skills/frontend/visual-regression-storybook-review/references/test-runner-and-chromatic-wiring.md

@@ -0,0 +1,56 @@
+# Test-Runner and Chromatic Wiring
+
+Use this reference when reviewing or configuring the Storybook `test-runner`'s `preVisit`/`postVisit` hooks, its CI invocation, Chromatic project setup, or when a user is unclear on the difference between the two. For axe-core/a11y gating specifics, see `accessibility-addon-gating.md`. For theme/variant coverage, see `theme-and-variant-coverage.md`.
+
+> Version note: hook signatures and helper exports (`getStoryContext`, `waitForPageReady`) live in `@storybook/test-runner` and have evolved across Storybook majors. Verify exact exports and signatures against the installed version via Context7 (`/storybookjs/storybook`) or the official docs before citing one as available.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> "We have Storybook tests" means visual regressions are covered.
+
+That is not necessarily true. A project can have:
+
+- a `test-runner` that only asserts `expect(canvas).toBeInTheDocument()`-style smoke checks, with no image snapshot step at all,
+- Chromatic connected but running in "notify only" mode with no branch protection requiring the check,
+- both tools installed, but neither one covering the components the team actually considers visually critical.
+
+"Storybook tests exist" and "visual regressions are gated" are different claims. Confirm which one is actually true before crediting a project with coverage.
+
+## Officially grounded shape
+
+Per Storybook's own documentation, the `test-runner` and Chromatic are described as complementary, not redundant:
+
+- **The `test-runner`** is a generic testing tool, built on Playwright, that can run locally or in CI and be configured or extended to run "all kinds of tests." It exposes a `preVisit`/`postVisit` hook API in `.storybook/test-runner.ts`:
+  - `setup()` runs once before the test runner starts.
+  - `preVisit(page, context)` runs before a story is rendered; `page` is Playwright's page object, `context` carries the story's id/title/name.
+  - `postVisit(page, context)` runs after a story is fully rendered; this is where image-snapshot assertions and `getStoryContext(page, context)` (to read the story's full parameters/args/argTypes) typically go.
+  - `waitForPageReady(page)` is a documented helper for image-snapshot testing that waits for the page -- including async items like images and fonts -- to finish loading before a screenshot is taken; skipping it is a common source of flaky screenshot diffs on slow-loading assets.
+- **Chromatic** is a cloud-based service that runs visual and interaction tests without the team having to set up the test-runner itself. It syncs with the git provider and manages access control for private projects. Storybook's own docs describe using the test-runner locally and Chromatic in CI as a valid pairing: use Chromatic for visual and component tests, and the test-runner for other custom tests.
+- Chromatic project configuration lives in `chromatic.config.json` (fields such as `projectId`, `buildScriptName`, `zip`, `debug`) rather than being hardcoded into CI invocation flags.
+
+## Non-negotiable design rules
+
+1. **Do not credit "Storybook tests pass" as visual coverage without confirming a diffing step exists.** A `test-runner` config with no image-snapshot assertion in `postVisit`, and no Chromatic connection, has zero visual-regression coverage regardless of how many stories exist.
+2. **Confirm the check is required, not advisory.** A connected Chromatic project that is not set as a required status check on the default branch's protection rules can be bypassed by any merge; "connected" and "gating" are different claims and must be verified separately (repo evidence: branch protection config, not just Chromatic dashboard presence).
+3. **Use `waitForPageReady` (or an equivalent explicit wait) before any screenshot assertion in `postVisit`.** Taking a screenshot before fonts/images finish loading produces non-deterministic diffs that erode trust in the whole suite and lead teams to loosen thresholds instead of fixing the real timing bug.
+4. **Do not run the test-runner without `preVisit`/`postVisit` review when adding a11y or visual checks.** These hooks are the only place axe injection and screenshot assertions can run per-story with access to `getStoryContext`; bolting checks on outside this API produces inconsistent coverage across stories.
+5. **When both the test-runner and Chromatic exist, confirm they aren't duplicating the same check with different tolerances.** Two visual-diff mechanisms with different pixel-diff thresholds on the same components is a maintenance and false-confidence problem, not defense in depth.
+
+## Safe verification targets
+
+- `.storybook/test-runner.ts` (or `.js`) -- confirm `preVisit`/`postVisit` hooks exist and what they assert.
+- `chromatic.config.json` and the CI workflow step invoking `chromatic` -- confirm `projectId` is present and the step is wired into a required CI job, not an optional/manual trigger.
+- Branch protection rules (repo settings, not just CI YAML) -- confirm the Chromatic and/or test-runner CI check is marked required before merge.
+- `package.json` `test-storybook` script and its CI invocation flags (e.g. `--ci`, coverage flags) -- confirm it's actually called in CI, not just defined locally.
+
+## When to push back
+
+Push back if the user asks for:
+
+- widening a `test-runner` image-snapshot diff threshold as the first response to flaky screenshots, before confirming `waitForPageReady` or explicit content masking is in place,
+- connecting Chromatic without also making it a required CI check, calling that "visual regression coverage,"
+- removing the test-runner because "Chromatic covers it," without confirming Chromatic's scope actually includes the custom assertions the test-runner was running.
+
+Those are shortcuts that produce the appearance of coverage without the substance.

package/skills/frontend/visual-regression-storybook-review/references/theme-and-variant-coverage.md

@@ -0,0 +1,51 @@
+# Theme and Variant Coverage
+
+Use this reference when auditing whether dark mode, RTL, and `prefers-reduced-motion` story variants have visual and accessibility coverage, or when non-deterministic content needs masking/mocking before a pixel diff is trustworthy. For the mechanics of the test-runner and Chromatic themselves, see `test-runner-and-chromatic-wiring.md`. For axe-core gating specifics, see `accessibility-addon-gating.md`.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> If the default-theme story passes visual and a11y checks, the component is covered.
+
+That is incomplete. A component's rendered DOM, computed contrast ratios, and layout can all differ meaningfully across:
+
+- **color scheme** (light vs. dark, or any custom theme the design system supports) -- contrast ratios computed by axe-core in a light-theme snapshot say nothing about the dark-theme token pairing, which is a distinct set of color values,
+- **text direction** (LTR vs. RTL) -- logical layout bugs (icon placement, padding asymmetry, text truncation direction) frequently only appear in RTL and are invisible in an LTR-only snapshot,
+- **motion preference** (`prefers-reduced-motion: reduce`) -- a component that only has an animated entrance story has no coverage confirming the reduced-motion fallback renders correctly, not just "does not animate."
+
+A visual-regression suite that only ever renders the default light/LTR/motion-enabled variant of each component has verified one of potentially four-plus meaningfully different rendered states, and will not catch a regression introduced in any of the others.
+
+## Officially grounded shape
+
+Storybook does not automatically render every theme/direction/motion-preference permutation of a story -- coverage of these dimensions is a function of how many story variants exist and whether decorators or globals feed them into each render. Confirm, as repo evidence rather than assumption, whether:
+
+- a dark-mode (or multi-theme) decorator/global exists and is exercised by dedicated stories, not just toggle-able in the manual Storybook UI,
+- RTL stories exist using the project's actual RTL mechanism (e.g. a `dir="rtl"` wrapper decorator), not just documented as "supported" in a design doc,
+- a `prefers-reduced-motion` variant exists, typically via a decorator that sets the media feature for the story's iframe, or via a dedicated reduced-motion story.
+
+`parameters.a11y.context` (see `accessibility-addon-gating.md`) determines what markup axe-core inspects per story -- confirm it is not silently scoped in a way that excludes the very wrapper (e.g. an RTL `dir` wrapper) whose correctness is under test.
+
+## Non-negotiable design rules
+
+1. **Do not count a single default-theme story as coverage for "the component supports dark mode."** Supporting a capability in code and having a regression-tested story for it are different claims; only the latter catches a regression.
+2. **Mask or mock non-deterministic content before adding any new theme/variant story to a visual diff, rather than after a flaky failure appears.** Timestamps, live avatars, randomized placeholder data, and animated content are common sources of false-positive diffs; the fix is explicit masking (e.g. a `mask` option, disabled animations, or seeded fixture data) applied at story-authoring time, not a loosened global threshold applied later.
+3. **Treat RTL coverage as a layout-logic concern, not a translation concern.** An RTL story does not need translated text to be useful -- it needs the same content rendered with `dir="rtl"` to catch physical-vs-logical CSS property bugs (e.g. `margin-left` instead of `margin-inline-start`).
+4. **Treat `prefers-reduced-motion` coverage as a distinct assertion from "does it animate," not a subset of it.** A story confirming the *entrance* animation looks right says nothing about whether the reduced-motion fallback (often a hard cut or fade) is also correct; test both if the component is animated.
+5. **Prioritize theme/variant coverage by actual usage risk, not exhaustive permutation.** A component used only in an admin-only, LTR-only internal tool does not need RTL coverage; a design-system primitive used across public, internationalized surfaces does. Recommend coverage proportional to blast radius, not maximal coverage for its own sake.
+
+## Safe verification targets
+
+- Story files for visually-critical components -- confirm the presence (or absence) of theme/direction/motion story variants, not just the default export.
+- `.storybook/preview.ts` decorators and globals -- confirm a theme-switching or `dir`-setting decorator exists and is actually wired into the stories claimed to cover it.
+- The test-runner's `postVisit` hook or Chromatic's captured snapshot list -- confirm the theme/variant stories are actually included in the set of stories being diffed, not excluded by a `tags` filter or story-level skip.
+
+## When to push back
+
+Push back if the user asks for:
+
+- claiming "dark mode is covered" based on a single manually-toggled preview in local dev, with no corresponding story or CI snapshot,
+- adding an RTL story with translated placeholder text but no `dir="rtl"` wrapper, which tests translation rendering but not the actual logical-CSS layout bug class RTL coverage exists to catch,
+- deferring reduced-motion coverage indefinitely on an animation-heavy component while treating it as low priority, without characterizing the actual user population affected (motion-sensitivity accommodations are an accessibility requirement, not a nice-to-have).
+
+Partial coverage presented as complete coverage is worse than an honestly documented gap.

package/skills/frontend/vue-composition-api-architecture-review/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: vue-composition-api-architecture-review
+description: Statically review Vue 3 Composition API code — composable extraction quality, reactivity-boundary correctness (ref/reactive/computed usage, destructuring-loses-reactivity pitfalls), and script-setup component organization — against Vue's own documented composable conventions and reactivity fundamentals.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: architecture
+---
+
+# Vue Composition API Architecture Review
+
+## Purpose
+
+Review Vue 3 composables and `<script setup>` components for the specific defect classes Vue's own documentation calls out — reactivity lost through destructuring, lifecycle hooks registered outside the synchronous setup window, impure `computed()` getters, and script-setup components that mix data-fetching, business logic, and presentation with no composable extraction — without re-litigating component prop design, template markup, styling, or SSR/hydration concerns in every response. This skill exists so those adjacent concerns stay out of scope and the review stays focused on the documented reactivity-boundary and composable-extraction catalog.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review a new or refactored composable (a `use*`-prefixed function) before merge,
+- diagnose a report that "reactive state doesn't update in the UI" after destructuring a composable's return value,
+- review a `<script setup>` component for organization and whether logic should be extracted into a composable,
+- decide whether a given `computed()` or lifecycle-hook usage is correct.
+
+Do not use this skill for:
+
+- Options API-only codebases with no Composition API usage and no stated migration plan — there is no reactivity-boundary or composable-extraction surface to review,
+- SSR-specific security concerns (session/auth-token handling inside composables, hydration mismatches) — hand off to `vue-ssr-security-review`,
+- a bug that requires live reproduction (Vue Devtools reactivity inspection, browser profiling) to confirm — static analysis can identify the missing `toRefs()`/guard, not prove which specific runtime instance broke.
+
+## Context7 Documentation Protocol
+
+- Resolve the Vue library ID with `resolve-library-id` (matched result: `/vuejs/vue`) before labeling any specific pattern as a reactivity-loss bug or a composable-convention violation.
+- `/vuejs/vue` is Vue's core source-and-test repository, not the prose docs site. Use `query-docs` against it to corroborate exact runtime behavior (e.g., the `computed({ get, set })` writable-computed shape, `reactive()`/`ref()` tracking mechanics) from source and unit tests. It does not reliably surface the narrative guidance in the Composables and Reactivity Fundamentals guides — for that guidance, use the `official_docs` URLs in this skill's `metadata.json` and label the claim `documentation-based`.
+- Before asserting a specific destructuring pattern loses reactivity, confirm which construct is being destructured: destructuring a `reactive()`-returned proxy loses reactivity on primitive-valued properties; destructuring a `ref()` or a `toRefs()`-wrapped object does not, because each extracted value is itself a ref. Do not apply a blanket "destructuring is unsafe" rule — check the return type first.
+- Read `package.json` first to confirm Vue 3.x is in use; Composition API and its documented composable conventions (including `<script setup>`) are Vue 3 features, not Vue 2.
+- If Context7 is unavailable, fall back to the `official_docs` URLs in this skill's `metadata.json` and label the claim `documentation-based, unverified against current release`.
+
+## Lean operating rules
+
+- For every composable in scope, first determine whether its return value is intended to be destructured by consumers. If yes, verify it returns individual refs or a `toRefs()`-wrapped reactive object — a plain `reactive()` object returned for destructuring is the documented reactivity-loss pitfall, not a style preference.
+- For every composable, verify the `use*` naming convention and verify that lifecycle hooks (`onMounted`, `onUnmounted`, `watch`, etc.) and other composables are called synchronously during the composable's/component's initial `setup()`/`<script setup>` execution — not inside an async callback, `await`-continuation, conditional, loop, or event handler registered after setup has returned. Vue's synchronous-registration requirement is a hard rule, not a lint nicety: a hook registered after an `await` silently fails to attach to the correct component instance.
+- For every `computed()` in scope, verify the getter is a pure read with no side effects (no state mutation, no async calls, no logging with side effects). A writable computed (`computed({ get, set })`) is the documented pattern for two-way-bindable derived state — do not flag its `set` function as an impurity; that is its intended role.
+- Review `<script setup>` components for responsibility mixing: data-fetching, validation/business logic, and presentation-only state all inline with no composable extraction. Flag extraction candidates only when the mixed logic is non-trivial and would reduce duplication or improve testability if extracted — do not flag a component for using one or two local `ref()`s that have no reuse potential.
+- Do not fabricate a reactivity-loss finding without showing the exact destructuring line and the specific property that would stop updating. A finding that only says "this might lose reactivity" without the concrete assignment is not a valid finding.
+- Never execute, build, or run application code as part of this review; this is a static-review skill (Read/Grep/Glob only).
+- Load only the reference needed for the concern in scope.
+
+## References
+
+Load these only when needed:
+
+- [Review workflow and findings contract](references/workflow-and-output.md) — use for the step-by-step review procedure, the reactivity/composable decision tree, and the required output shape.
+- [Reactivity boundaries](references/reactivity-boundaries.md) — load only when reviewing `ref()`/`reactive()`/`computed()` usage, a suspected destructuring-loses-reactivity bug, or `toRef()`/`toRefs()`/`unref()` interop code.
+- [Composable and script-setup conventions](references/composable-and-script-setup-conventions.md) — load only when reviewing composable naming/structure, lifecycle-hook registration timing, or `<script setup>` responsibility mixing and extraction candidates.
+
+## Response minimum
+
+Return, at minimum:
+
+- the composable(s) and/or component(s), files, and specific call sites in scope,
+- ranked findings with file:line evidence, defect category (reactivity-loss, lifecycle-timing, computed-impurity, or extraction candidate), and a concrete fix sketch matching the docs' recommended pattern,
+- for every reactivity-loss finding, the exact destructuring line and the property that would stop updating,
+- evidence level per finding (`repo evidence`, `documentation-based`, or `inference`),
+- verdict (approve / approve-with-notes / block),
+- open questions or scope the review could not cover (e.g., "requires Vue Devtools reactivity inspection to confirm at runtime").