Convex Performance Audit
Diagnose and fix Convex read amplification, subscription churn, OCC conflicts, and function-limit pressure when a feature feels slow or Insights flags hot paths.
Overview
Convex Performance Audit is an agent skill most often used in Ship (also Operate) that diagnoses Convex read, subscription, and write-contention problems one class at a time.
Install
npx skills add https://github.com/get-convex/agent-skills --skill convex-performance-auditWhat is this skill?
- One problem class at a time: reads, subscriptions, write contention, and Convex function limits
- Maps triggers to `npx convex insights --details` signals (bytes/documents read, OCC conflicts)
- Guards against over-engineering—no digest tables or migration-heavy rollouts without measured hot paths
- Covers low-freshness paths using reactivity where point-in-time reads suffice
- Patterns to fix sibling functions sharing the same performance anti-pattern
Adoption & trust: 62.2k installs on skills.sh; 31 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Convex feature is slow, Insights shows brutal reads or OCC retries, and you are unsure whether to add indexes, change fetch strategy, or leave the code alone.
Who is it for?
Indie builders on Convex with user-visible slowness, Insights warnings, or recurring mutation conflicts after ship.
Skip if: Greenfield Convex setup, auth-only tasks, schema-only migrations, or micro-optimizations with no measurable or user-visible pain.
When should I use this skill?
A Convex page or feature feels slow or expensive; convex insights --details reports high bytes read, documents read, or OCC conflicts; OCC conflict errors or excessive mutation retries; high subscription count or functio
What do I get? / Deliverables
You get a prioritized, evidence-backed fix plan for the dominant bottleneck—reads, reactivity, contention, or limits—without unnecessary migrations.
- Problem-class diagnosis (reads vs subscriptions vs contention vs limits)
- Recommended fixes with guardrails against premature structural changes
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Performance audits belong on the shipping shelf because they gate safe releases when latency, cost, or mutation retries threaten production readiness. Perf is the canonical subphase for measurable throughput, bytes-read, and transaction-limit work before and after deploy.
Where it fits
Profile a dashboard query before launch when Insights shows excessive documents read per request.
Investigate post-deploy OCC conflict alerts without rolling back the entire release.
Reproduce slow UI updates tied to high subscription count in staging.
Refactor sibling queries that share the same N+1 read pattern after growth spikes traffic.
How it compares
Use instead of guessing index changes from generic database advice—this skill is Convex Insights and OCC aware.
Common Questions / FAQ
Who is convex-performance-audit for?
Solo and indie developers running Convex-backed apps who need structured performance triage tied to Convex Insights and real user-visible symptoms.
When should I use convex-performance-audit?
During Ship perf hardening when launch prep exposes hot queries; in Operate when monitoring shows read amplification or OCC spikes; and whenever Insights details flag documents read or conflict retries.
Is convex-performance-audit safe to install?
Treat it as guidance that may recommend schema or query changes—review the Security Audits panel on this Prism page and validate migrations in a dev deployment before production.
SKILL.md
READMESKILL.md - Convex Performance Audit
# Convex Performance Audit Diagnose and fix performance problems in Convex applications, one problem class at a time. ## When to Use - A Convex page or feature feels slow or expensive - `npx convex insights --details` reports high bytes read, documents read, or OCC conflicts - Low-freshness read paths are using reactivity where point-in-time reads would do - OCC conflict errors or excessive mutation retries - High subscription count or slow UI updates - Functions approaching execution or transaction limits - The same performance pattern needs fixing across sibling functions ## When Not to Use - Initial Convex setup, auth setup, or component extraction - Pure schema migrations with no performance goal - One-off micro-optimizations without a user-visible or deployment-visible problem ## Guardrails - Prefer simpler code when scale is small, traffic is modest, or the available signals are weak - Do not recommend digest tables, document splitting, fetch-strategy changes, or migration-heavy rollouts unless there is a measured signal, a clearly unbounded path, or a known hot read/write path - In Convex, a simple scan on a small table is often acceptable. Do not invent structural work just because a pattern is not ideal at large scale ## First Step: Gather Signals Start with the strongest signal available: 1. If deployment Health insights are already available from the user or the current context, treat them as a first-class source of performance signals. 2. If CLI insights are available, run `npx convex insights --details`. Use `--prod`, `--preview-name`, or `--deployment-name` when needed. - If the local repo's Convex CLI is too old to support `insights`, try `npx -y convex@latest insights --details` before giving up. 3. If the repo already uses `convex-doctor`, you may treat its findings as hints. Do not require it, and do not treat it as the source of truth. 4. If runtime signals are unavailable, audit from code anyway, but keep the guardrails above in mind. Lack of insights is not proof of health, but it is also not proof that a large refactor is warranted. ## Signal Routing After gathering signals, identify the problem class and read the matching reference file. | Signal | Reference | | -------------------------------------------------------------- | ----------------------------------------- | | High bytes or documents read, JS filtering, unnecessary joins | `references/hot-path-rules.md` | | OCC conflict errors, write contention, mutation retries | `references/occ-conflicts.md` | | High subscription count, slow UI updates, excessive re-renders | `references/subscription-cost.md` | | Function timeouts, transaction size errors, large payloads | `references/function-budget.md` | | General "it's slow" with no specific signal | Start with `references/hot-path-rules.md` | Multiple problem classes can overlap. Read the most relevant reference first, then check the others if symptoms remain. ## Escalate Larger Fixes If the likely fix is invasive, cross-cutting, or migration-heavy, stop and present options before editing. Examples: - introducing digest or summary tables across multiple flows - splitting documents to isolate frequently-updated fields - reworking pagination or fetch strategy across several screens - switching to a new index or denormalized field that needs migration-safe rollout When correctness depends on handling old and new states during a rollout, consult `skills/convex-migration-helper/SKILL.md` for the migration workflow. ## Workflow ### 1. Scope the problem Pick one concre