cursor-kenji

Cross-page UX audit for user stories, task completion, and information architecture — the layer audit-ux (per-page heuristics) doesn't cover. Derives real user stories from routes/nav/CTAs (not invented personas), scopes depth by audit trigger (KPIs dropping / complaints / redesign / pre-launch), audits IA structurally (click depth, orphan pages, dead ends, label consistency, grouping vs mental model, findability/first-click), then walks every core story end-to-end in a headed browser producing a task-completion matrix with friction logs. Evidence-disciplined: validates with analytics/funnels/drop-offs when available, otherwise marks findings as expert-judgment hypotheses — never presents taste as data. Reports impact×effort quick-wins vs roadmap. Use when "audit user flows", "user story audit", "information architecture / IA audit", "can users find X", "users get lost", "navigation audit", "funnel drop-off", "task completion", or "audit-ux-journeys". Per-page heuristics/microcopy stay with audit-ux.

Audit user experience quality using research-backed frameworks: Nielsen Norman Group's 10 usability heuristics, Intuit Content Design System for microcopy, Google's HEART metrics, and Laws of UX (Fitts's, Hick's, Miller's, Jakob's, cognitive load). Evaluates information architecture, user flows, error recovery, onboarding, content clarity, and interaction patterns. Uses browser MCP for live walkthrough, Firecrawl for current NN/g research, and Sequential Thinking for complex flows. Generic — works with any webapp. Use when evaluating usability, reviewing user flows, auditing microcopy, checking UX heuristics, assessing cognitive load, reviewing onboarding, or when the user mentions UX audit, usability review, heuristic evaluation, content audit, interaction design review, or user flow analysis. Focuses on per-page EXPERIENCE — for visual design-system compliance (tokens, components, dark mode) use audit-uiux-design-system; for cross-page user-story/IA/journey audits use audit-ux-journeys.

Read-only audit for payment/money-movement systems, scope-gated so a simple Stripe-Checkout site and an in-house ledger/gateway each see only relevant findings. Checks the things that lose money or trigger PCI liability: idempotency on every mutation (double-charge on retry), double-entry append-only ledger, payment state machine (no double-capture), sync-auth vs async-webhook flow, HMAC + event-id webhook dedup, 3-way reconciliation vs PSP settlement, fraud/velocity + 3DS/SCA, multi-currency in minor units, PCI DSS v4.0.1 (never log PAN, tokens only, key rotation), and resilience (PSP timeout, partial ledger write, breaker). Uses the Stripe MCP for version-anchored provider checks when the PSP is Stripe. Use when "audit payment system", "payment gateway audit", "double charge / idempotency", "ledger / reconciliation", "webhook / 3DS / PCI", or "audit-payment-system". Defers per-call resilience to audit-resilience, PCI/secrets to audit-security, ledger schema to audit-db-schema.

Apply modern backend patterns — auth middleware, caching strategies, background queues, rate limiting, and serverless/edge function design — across stacks (examples use Next.js, Node, and Supabase; adapts to your detected ecosystem). Use when the user says "backend architecture", "queue jobs", "caching layer", "rate limiting", "server actions", "edge function", "microservices", "authentication pattern", "circuit breaker", "outbox pattern", "saga", "bulkhead", "hexagonal architecture", "API gateway", or "BFF" (see references/architecture-patterns.md for the distributed-systems patterns). Pairs with design-api, audit-security, backend-realtime, and audit-backend-architecture (the read-only gap report). Do NOT use for database schema design (audit-db-schema) or pure frontend work.

Read-only audit AND decision advisor for backend/distributed-systems architecture, topology-gated so a Next.js/Supabase monolith and a Kubernetes fleet each see only relevant findings. Reports which patterns are present (maturity matrix, file:line), then — following "start simple, earn every pattern" — recommends which to adopt now, adopt-when-[trigger], or defer as premature, flagging over-engineering and the distributed-monolith anti-pattern. Covers sync request/response vs event-driven, cache-aside, database-per-service, API gateway, BFF, circuit breaker, bulkhead, outbox + CDC, saga, CQRS, hexagonal, strangler-fig, service mesh, cell-based, mTLS, tracing + SLOs, contract testing. Use when "audit backend architecture", "which pattern should I use", "am I over-engineering", "sync vs event-driven", "cache-aside/CQRS/saga/db-per-service", "microservices resilience review", or "audit-backend-architecture". Defers per-call resilience to audit-resilience; fixes via backend-patterns.

Audit CI/CD pipelines (GitHub Actions) for cost, speed, and safety. Use when the GitHub Actions bill is high, when the user mentions Actions minutes, runner cost, workflow cost, slow CI, artifact/cache storage, or wants a CI/CD / workflow audit. Finds double-billing triggers, missing concurrency, macOS/large runners on push, missing path filters, long artifact retention, and doomed jobs — then proposes fixes that never delete tests or break deploys.

Co-author structured documents (specs, PRDs, RFCs, ADRs) through a 3-stage workflow: context gathering, drafting, and reader testing. Use when writing proposals, technical specs, decision docs, or similar structured content.

Write clear, developer-friendly documentation — READMEs, API references, code comments, and changelog entries — tailored to the audience and the project's voice. Use when the user says "write docs", "document this API", "update the README", "add code comments", "changelog entry", or "explain this for contributors". Covers structure, examples, and jargon choices. Pairs with deploy-npm, audit-i18n. Do NOT use for in-product UX copy (enhance-web-ux) or marketing copy.

Turn a plain-text README into a visually rich showcase with a theme-aware hero image, a feature tour grid, an optional animated guided-tour GIF, and updated tech badges. Captures live screenshots via Playwright MCP in both dark and light mode at hero-quality 1600x1000, pairs them with `<picture>` for auto theme-swap, and inlines them into the README using GitHub-supported HTML. Optionally records a guided-tour `.gif` (autoplays inline on github.com via `record-readme-tour.mjs`) for an animated demo above the static screenshots. Works with any web app that has a live URL or local dev server. Use when asked to "enhance README", "make README prettier", "add screenshots to README", "showcase the app in README", "design the README", "add hero image", "spice up README", "make README more fun", "add animated demo to README", "record a tour GIF", or "make a README GIF".

Audit a full-stack app against the RealWorld ("Conduit") reference — its formal API spec, shared Bruno/Hurl E2E suite, and closest-stack reference implementation — to find what is implemented correctly, partially, or not at all across frontend, backend, and data layer. Auto-detects whether to run strict spec conformance (the repo IS a RealWorld build) or benchmark the repo's own domain against RealWorld's production-relevant patterns, and bows out cleanly on non-CRUD/non-web repos. Read-only: produces a prioritized gap report and hands remediation to other skills. Use when "audit against realworld", "compare my app to realworld", "conduit conformance", "is my full-stack app complete", "full-stack gap check", or "what's missing to reach production". RealWorld is a completeness/pattern reference, not a production bar — real hardening is delegated to audit-security / plan-* skills.

Read-only audit for the non-functional "20%" AI agents systematically skip: timeouts, retries with backoff+jitter, circuit breakers, idempotency keys, rate limiting, graceful degradation/fallbacks, cancellation, audit logging on sensitive actions, and PII handling in logs. Inventories every external call, mutation, webhook, and payment path and marks each concern Implemented/Partial/Missing with file:line, severity, and the exact skill to fix it. Use when "is this production-ready", "resilience audit", "will this survive real traffic", "audit retries/timeouts/idempotency", "reliability review", "the 80% problem", or "audit-resilience". Produces a prioritized report only — remediation is delegated to backend-error-handling / backend-observability / backend-patterns / plan-* skills.

Install guardrails-as-code into a repo so AI/vibe-coding can't keep reintroducing the same classes of problems (leaked secrets, injection, off-system styles, untested code, hallucinated or vulnerable dependencies, destructive shell/DB ops). Audits what protection already exists, then sets up a tailored stack: agent policy files (.cursor/rules + AGENTS.md), a pre-commit hook (secret scan + SAST + lint/typecheck), a CI gate that treats agent output as untrusted, and lint-as-policy rules. Use when "set up guardrails", "stop vibe-coding regressions", "add pre-commit security checks", "protect the repo from AI mistakes", "add CI security gates", "governance for AI code", or "enhance-agent-guardrails". Configures tooling; CI/secret-scanner changes are flagged for human review before they block merges.

Audit an existing app's design system and current motion, then apply coherent, performant, accessible motion using the right-sized 2026 stack — CSS/tw-animate-css for utility transitions, Auto-Animate for zero-config list/layout changes, Motion (motion.dev, ex-Framer Motion) for component transitions/gestures/presence, and GSAP only for complex timelines. Defines a motion-token SSOT (durations/easings) coherent with the app's existing scale, respects prefers-reduced-motion, and keeps everything on transform/opacity at 60fps. Use when "add motion", "animate the app", "make it feel alive", "motion pass", "add micro-interactions across the app", or "enhance-motion". Distinct from design-motion (from-scratch cookbook): this audits the existing system first and layers motion coherently on top. Applies changes and verifies them.

Build or upgrade web forms to production quality: accessible structure (labels, fieldsets, autocomplete, correct input types), schema-driven validation with client↔server parity, inline errors correctly associated for screen readers, complete interaction states (loading, disabled, success, error, empty), multi-step flows, unsaved-changes guards, and optimistic/pending submit feedback. Auto-detects the form + validation stack (react-hook-form, Formik, TanStack Form, native; zod/yup/valibot). Use when "improve this form", "form validation", "accessible form", "multi-step form", "form error handling", "the form UX is bad", or "enhance-web-forms". Applies changes and verifies them. Delegates deep a11y to audit-accessibility, submit-contract checks to audit-fe-api, and micro-feedback to design-motion.

Consolidate a design system that has drifted across many vibe-coding sessions and developer handoffs into one single source of truth. Detects competing tokens, duplicate/near-duplicate components, naming drift, mixed icon libraries, and ad-hoc arbitrary values; reconciles each conflict by picking the best-of-both canonical form; migrates all usages via mechanical codemod; and installs lint guardrails so drift can't recur. Establishes a 3-layer W3C token taxonomy (primitive → semantic → component). Use when "clean up the design system", "resolve design conflicts", "our UI is inconsistent across pages", "consolidate tokens/components", "streamline the design system", "keep the design SSOT", or "housekeep-design". This is the execution arm of plan-uiux-unification (which only plans) and the design counterpart of workflow-housekeep (which cleans files).

Instrument features so errors, traces, and logs are correlated from the first line. Use when adding logging, tracing, or monitoring; wiring Sentry, Langfuse, or structured logs; or when asked "add logging", "instrument this", "why can't I debug prod", "correlate the error to the trace", "redact PII from logs", "set up alerts/SLOs".

Close an approved plan with zero plan-related deferrals: implement every unfinished item, absorb every connected out-of-scope/follow-up/nice-to-have item parked by prior runs, fix newly exposed gaps, and run the full applicable verification ladder. Use when a plan was marked done with work deferred, or the user says "complete everything", "don't defer", "fix out of scope too", "finish the whole plan", "close every TODO", or invokes /complete-everything. Distinct from burndown-full, which proves mechanical pattern coverage; this skill closes intent, behavior, and verification gaps.

Wire ETL, ingestion, cron, edge-function, and queue jobs correctly. Use for "build a pipeline", "sync X into Y", "nightly aggregation", "cron double-counts", "dedupe", "backfill", "the numbers are wrong after a retry". Bakes in idempotency, atomic writes, data contracts, dead-letter, and observability.

Cross-surface UIUX separation skill for hybrid web apps that ship as PWA + iOS + Android via Capacitor (or Tauri / Expo Web / Ionic / RN-Web). Use when a previous UI/UX sweep "improved one surface and broke the other" — desktop polished but mobile cramped, or mobile native but desktop wastes space. Also use when the project has ad-hoc useIsMobile / isNative branches scattered across components, a single md: breakpoint doing double duty as "is desktop" and "wider slot", or per-component platform styling instead of mode tokens. Establishes three orthogonal axes — form factor (compact/medium/expanded), platform (web/ios/android), pointer (fine/coarse) — and a three-layer architecture (context hook, mode tokens, container-query primitives) so one sweep can enhance one axis without degrading the others. Catches axis conflation in a single boolean, hover-only affordances on native shells, and SSR/Capacitor first-paint mismatch. For pure visual polish on a single surface, use enhance-web-ui first.

Generative, NN/g-grounded page enhancement skill. Given a route, screen, or component, it produces concrete, design-system-compliant code changes that replace generic, AI-templated, or "stacked" UI with intelligent, context-aware layouts. Inventories the page's data domain and primitives FIRST, maps each pain point to a Nielsen Norman heuristic, then proposes the smallest change using an existing primitive (Badge, Button, Card, Tooltip, semantic token). Replaces empty cells with semantic data, fixes label-wrap/overflow at the helper level, and verifies live across viewports via the browser MCP. Use when the user says "enhance this page", "make /xxx better", "this page feels AI-generated", "fix UX of /xxx", "improve information density", "icons all look the same", or asks for any non-trivial UX improvement on a screen. Generic across stacks. For visual-token compliance use audit-uiux-design-system; for a heuristic report use audit-ux.

Turn an agent's own failure — a premature stop, a false "done", a reward- hacked check, a missed file, a broken handoff — into a durable improvement to the harness (skills, rules, hooks, subagents, verification scripts) plus a regression check that would have caught it. Diagnose the root failure mode, make the smallest durable fix, add a repeatable guard, validate it, and record the lesson. Use when "the agent stopped early again", "it said done but wasn't", "it gamed the test", "improve the skills so this doesn't recur", "add a guard for this", "close the loop on that failure", or after any run that ended wrong. Operates on this toolkit itself.

Handle Capacitor platform depth beyond UI: plugins, OTA, deep links, push, offline, native CI/CD, App Store / Play Store submission, Apple preflight, security scan, Cordova migration. Use for "add push notifications", "deep linking", "OTA update", "native build CI", "App Store rejection", "migrate to Capacitor".

Fix React Native / Expo performance, build, and upgrade issues. Use for jank, frame drops, slow startup, large bundles, memory leaks, Hermes, FlashList, Reanimated, Turbo Modules, Android 16KB alignment, or RN/Expo version upgrades.

Polish an existing React Native screen to feel intentional, native, and human-crafted. Catches RN-specific silent failures — safe area violations, sub-minimum touch targets, keyboard occlusion, JS-thread animation jank, gesture conflicts, tab-bar content clipping, double safe-area insets, and FlatList re-render storms — alongside the platform-agnostic composition failures shared with the web skills (active-state mass mismatch, brand-color competition, monochromatic surfaces, information duplication per screen, left-anchored stacks). Use for "this screen looks off", "feels clunky on iOS", "Android version looks wrong", "jank when scrolling", "button is unreachable", or any RN-specific UX polish pass. Applies to bare React Native, Expo bare workflow, and Expo managed workflow. Pairs with mobile-emulator-start and mobile-emulator-test. For web/PWA surfaces use enhance-web-ui or enhance-web-ux instead.

Pass/fail health check across every Mushi Mushi pipeline component — CLI credentials, API reachability, edge functions, BYOK key pool, QA cron. Use when "is mushi working", "mushi health check", "check mushi pipeline", "mushi deploy check", "pipeline not responding", or right after setup.

Full end-to-end Mushi Mushi integration smoke test: bug capture → AI triage → story mapping → TDD test generation → approval → execution → PDCA cycle. Use when "test mushi integration", "verify full pipeline", "mushi e2e check", "does mushi work end-to-end", "smoke test mushi", or after deploying changes.

Prove the working environment is actually runnable before starting a long or autonomous task, so a multi-hour run does not fail at the finish line on a missing tool, dependency, service, or credential. Detect the stack, verify runtimes and package installs, confirm required services and env vars are reachable (without printing secrets), and confirm the real verification commands execute. Use when "set up the environment", "is this ready to run", "before we start the big task", "preflight the repo", "why won't the tests run", or at the start of any burndown / complete-everything / long agent run.

Turn raw feedback — bug reports, user complaints, review comments, Sentry issues, QA findings, audit/red-team output — into deduplicated, durable, trackable tickets and drive each to production-verified closure. Normalize and cluster incoming signals, dedupe against existing issues, write clear reproducible tickets, prioritize by impact, fix via the right skill, and close only after the fix is verified live. Use when "triage this feedback", "turn these reports into tickets", "process the bug backlog", "handle these review comments", "close the loop on QA findings", or "manage incoming issues". Bridges audit/QA/monitoring outputs into complete-everything and workflow-fix-and-ship.

Drive an entire repository to a fully green baseline — typecheck, lint, tests, and build all passing from a clean checkout — when the user has explicitly authorized fixing pre-existing debt. Enumerate every failing gate, externalize the worklist, fix root causes in batches, and prove green with a fresh from-scratch run. Use when "make the repo green", "get CI passing", "fix all the failing tests", "clear the typecheck errors", "zero lint errors", "make the build pass", or "clean up the baseline". Distinct from complete-everything (closes one plan's connected scope) and burndown-full (one searchable pattern) — this closes the whole repository's health gates.

Take merged, repository-green code all the way to a verified, monitored production release for any app stack. Confirm the target and the exact source revision, deploy (or trigger the deploy pipeline), verify the intended revision is actually live, smoke-test critical flows against production, then watch error/latency signals through a defined stability window and either confirm stable or execute an explicit rollback/hotfix. Use when "ship it", "deploy to production", "release this", "go live", "roll this out", "promote to prod", or "cut a release" for a running application (not an npm package — use deploy-npm for that). Complements deploy-verify with the observe-and-roll- back tail.

Stop vibe-coding with a spec → plan → TDD loop before writing a line. Use for any non-trivial feature, refactor, or bug fix on web, React Native, or Capacitor. Use when asked to "build", "implement", "add a feature", "this keeps breaking", "do it properly", or when LLM output keeps being wrong.

Third-party skill — Emil Kowalski's design engineering philosophy (UI polish, component design, animation craft). Use when building or reviewing UI, animations, micro-interactions, Sonner-style components, or when the user mentions emil-design-eng or thirdparty-emil-design-eng.

Third-party skill — reviews UI code for Vercel Web Interface Guidelines compliance (accessibility, focus, forms, animation, performance, copy). Use when auditing interfaces, reviewing UI PRs, or when the user mentions Vercel guidelines, web interface guidelines, or /thirdparty-web-interface-guidelines.

Release npm packages end-to-end: Changesets version bump, CHANGELOG update, GitHub Actions OIDC publish, and post-release verification. Use when the user says "release to npm", "publish this package", "ship a new version", "cut a release", "update the changelog", or combines a package name with a release verb. Covers monorepo and single-package workflows. Pairs with deploy-verify, docs-writer. Do NOT use for non-npm deploys (Vercel, Docker) or internal release notes only.

Run a PDCA quality audit on LLM/AI features: traces, prompts, costs, evals, grounding, hallucination. Use for "audit LLM", "check Langfuse", "audit prompts", "check AI quality", "audit AI costs", "check traces", "audit eval scores", "verify AI pipeline".

Third-party skill — design intelligence for professional UI/UX (the full style catalog, palettes, typography, UX guidelines). Generates tailored design systems via Python search scripts. Use when building, designing, or reviewing UI/UX, or when the user mentions ui-ux-pro-max or thirdparty-ui-ux-pro-max.

Audit code for security vulnerabilities and best practices. Use when reviewing security, checking for vulnerabilities, auditing auth code, or when the user mentions security concerns. Integrates Firecrawl for researching current OWASP guidelines and CVEs, Sentry MCP for checking production security-related errors, and automated codebase scanning.

Audit documentation against actual code behavior and plan corrections — no rewrites in this pass. Drift taxonomy (stale, missing, phantom, contradictory, onboarding-breaking, inline rot, API-contract drift) with code-as-source-of-truth methodology. Onboarding-drift checks against .env.example and CLI --help; docs-as-code guardrails for same-PR updates. Docs describe real current behavior — never aspirational or invented. Use when asked to "docs drift", "sync docs with code", "audit documentation", "stale README", "onboarding docs broken", "doc sync plan", "phantom docs", or "docs out of date".

Measure-don't-guess performance audit across web, mobile, backend, and data layers — produces burndown and optimization plan with no fixes in this pass. No fabricated metrics; every issue needs a measured baseline or [NEEDS PROFILING]. Research-backed proposals for React (code-split, memo, react-window, startTransition), RN (Hermes, JSI, <2s cold start), data N+1/index work with EXPLAIN, and prevention via Lighthouse CI budgets + RUM. Mobile thresholds stricter than web CWV. Use when asked to "performance audit plan", "perf burndown", "measure before optimize", "bundle size audit", "LCP slow", "N+1 audit plan", "plan performance improvements", or "Core Web Vitals audit".

OWASP Top 10 security audit with Supabase-first methodology — RLS pass, bundle/secret scan, auth-path tracing, dependency CVEs. Plan only, no patches or destructive testing. Never paste secret values — location + rotation flag only. Research-backed: tables without RLS and service_role in client bundle as top critical classes. Use when asked to "security audit plan", "OWASP audit", "RLS audit", "Supabase security review", "hardening plan", "secrets scan plan", "plan security fixes", or "security burndown".