ravie

Use this whenever a PR has a Vercel preview URL and needs browser QA against acceptance criteria — happy path, errors, empty states, responsive behavior, a11y basics — even if the user just says "check the preview". Requires a preview URL. NOT for release/deploy-readiness checks (no preview needed there) — use deploy-ready.

Plan and split work into parallel worktree sessions. Use whenever the user wants to work on multiple tasks at once, mentions parallel sessions, worktrees, "split this up", "dispatch", or lists several independent tasks for one work session.

Use this skill when implementing or reviewing UI that needs semantic HTML, keyboard navigation, focus management, ARIA labels, color contrast, reduced motion, forms, modals, or public-facing pages. Do not use as a standalone product-planning or backend workflow; pair it with design-system-ui, responsive-ui, or vercel-preview-qa when broader UI review is needed.

Use this skill when working across client, agency, consulting, or personal projects where code, data, credentials, prompts, or reusable patterns could leak between contexts. Do not use for ordinary single-project work with no cross-client or cross-workspace boundary risk.

Use this skill when creating components, implementing Figma designs, cleaning inconsistent styling, adding or reviewing tokens, spacing, typography, or component variants. Do not use for backend work, feature scoping, or visual QA that requires a live preview instead of design-system decisions.

Use this skill when importing ChatGPT or Claude exports, old Notion databases, local notes, or messy knowledge dumps into a durable knowledge system after redaction, deduplication, and classification. Do not use for live project planning, raw unredacted client data, or content that should remain out of Notion.

Use this skill when repeated corrections, a significant feature, a slow debugging session, or a weekly review create evidence for reusable patterns and skill or CLAUDE.md updates. Do not use for one-off annoyances, immediate implementation, or unverified patterns without evidence.

Use this skill when an action may write externally, delete, overwrite, force-push, deploy, migrate, touch secrets, affect production, access customer/client data, or when the permission tier is uncertain. Do not use for read-only inspection or drafting that clearly stays local.

Use this skill when implementing or reviewing responsive layouts, mobile-first behavior, breakpoints, touch targets, overflow, or layout bugs across mobile, tablet, and desktop. Do not use for backend work, generic visual polish, or accessibility-only issues handled by accessibility-ui.

Use this skill when you are unsure which Ravie skill applies, need to sequence multiple workflows, or need a human-readable routing reference for a mixed request. Do not use when the request clearly matches one specific skill; use that skill directly.

Use this skill when Notion, Linear, GitHub, or other sources disagree; when duplicate task/docs sources appear; or when it is unclear where information should live. Do not use for normal feature implementation or single-system edits with no source-of-truth conflict.

Use this skill when UI text is vague, generic, missing, or confusing, including buttons, errors, empty states, loading messages, success feedback, and recovery guidance. Do not use for long-form marketing copy, PRDs, or product positioning that belongs to growth-launch-pack or requirements-griller.

Use this skill when evaluating whether Ravie skills, workflows, routing, or approval gates are working after real usage, recurring friction, skipped gates, or a monthly health check. Do not use for product feature work or to blame a skill without evidence from actual sessions.

Use this whenever the user mentions Linear or task tracking — creating, updating, splitting, linking, triaging, or summarizing issues, projects, blockers, or acceptance criteria — even just "make a ticket for that". NOT for durable knowledge (notion-brain) or implementation (issue-to- pr).

Use this whenever durable knowledge should be written to or found in Notion — PRDs, decisions, runbooks, briefs, learnings — or the user says "save this", "document this", "add to the wiki". Notion writes need approval. NOT for task status — that's Linear.

Use this whenever creating or improving a Ravie skill — the user says "make this a skill", "we keep repeating this", or a workflow or correction has recurred enough to codify. Also owns evaluating existing skills after real usage. NOT for one-off tasks.

Use this whenever you build or review ANY frontend UI — components, layouts, forms, styling, or user-facing text — even if the user just says "build the page". Covers design tokens, mobile-first layout, accessibility, and UI copy. NOT for animation (animation-motion), WebGL (threejs-motion- performance), or preview QA (vercel-preview-qa).

Update docs/STATE.md with current session state. Use whenever the user says "wrap up", "handoff", "end session", "save state", "update state", or signals they are stopping work — even mid-task.

Use this after any non-trivial code change, AI or human, before committing: new components, services, API routes, module boundaries, or anything touching auth, permissions, database, or RLS — even if the user only says "ready to commit". Skip only typo or docs-only edits.

Use this before implementing against any version-sensitive or unverified API: package upgrades, SDK and framework APIs (Next.js, Supabase, Vercel, Three.js, MCP, auth, browser APIs), or any external API you would otherwise write from memory unverified this session.

Use this whenever something fails before it has shipped — failing tests, broken builds, wrong UI behavior, preview errors — and the cause is unknown, even if the user just pastes an error. Diagnose before fixing. Production failures (main branch, live users) → observability-incident- loop.

Use this whenever a branch or PR is about to merge or deploy to production — "ship it", "ready to merge", "deploy" — especially with new env vars, external services, metadata, or secrets. Runs the release checklist. NOT preview-URL browser QA — that's vercel-preview-qa.

Use this ONLY for production failures: Vercel production errors, Supabase outages, Actions failing on main, automation crashes, user-reported live bugs. Runs the incident loop: stabilize, diagnose, fix, prevent. Local, preview, or pre-merge failures → debug-root-cause.

Use this whenever a request or idea is vague, ambiguous, or high-stakes — "I want something like…", "can we add…" with no acceptance criteria. Asks one question at a time until scope is clear. Output feeds idea-to-prd-tracer or issue-to-pr.

Use this whenever adding, polishing, or debugging CSS/JS UI transitions or animations — the user says "animate", "transition", "motion", or "feels janky", or motion needs pre-launch polish. NOT for Three.js/WebGL/canvas work — use threejs-motion-performance.

Use this whenever the user mentions cron jobs, scheduled tasks, systemd timers, VPS automation, job retries, health checks, or automation secrets — creating, changing, debugging, or retiring them — even if they just say "my nightly job failed".

Use this whenever the user starts a workday or says "where were we", "what's the status", "catch me up", or needs one summary spanning Linear, GitHub, Vercel, Supabase, and Notion. NOT for single-system lookups — query that system directly.

Use this whenever a durable decision gets made — tech choice, tool, convention, scope cut, trade- off — or the user says "let's go with", "we decided", or "from now on". Record it as an ADR so future sessions don't re-litigate. NOT for task status (Linear) or temporary notes.

Use this whenever converting a Figma frame or Lovable prototype into an implementation plan — component architecture, token map, states, QA criteria — even if the user just pastes a design link and says "build this". Requires an accessible design reference.

Use this for standalone git/GitHub operations — branch management, commit hygiene, PR creation or cleanup, CI failure triage, releases, remotes — when the work is NOT implementing an approved Linear issue end-to-end (that's issue-to-pr). Never push to main.

Use this whenever the user asks for positioning, competitor research, idea-viability checks, SEO briefs, CRO review, landing-page strategy, or launch plans — any marketing or growth artifact, even if they just say "how do I launch this". NOT for implementation or code.

Use this when a clear, validated feature idea needs to become a PRD, Linear issues, and a first tracer-bullet plan — the user says "spec this out", "turn this into issues", "make a PRD". If the idea is still vague or unscoped, run requirements-griller first.

Use this whenever the user wants to implement an approved Linear issue that has acceptance criteria — "build PROJ-42", "implement this issue", "pick up the next ticket". Covers the full loop: branch, tracer bullet, checks, preview, PR. The daily driver for feature work.

Use this whenever setting up Claude Code in a repo — the user says "onboard this project", "set up CLAUDE.md", "install the skills or hooks" — or when CLAUDE.md is missing, stale, or broken. NOT for feature work inside an already-onboarded repo.

Use this whenever touching Supabase: tables, columns, indexes, migrations, RLS policies, auth flows, storage policies, edge functions, or service-role keys — even if the user just says "add a field". Every schema change gets a migration; every user-facing table gets RLS.

Use this whenever the work involves Three.js, WebGL, canvas rendering, shaders, or GPU-heavy effects — adding, reviewing, or optimizing frame rate, bundle impact, fallbacks, or memory cleanup. NOT for CSS/JS UI transitions — use animation-motion.