Convex Performance Audit

1---2name: convex-performance-audit3description: Audits and optimizes Convex application performance across hot-path reads, write contention, subscription cost, and function limits. Use this skill when a Convex feature is slow or expensive, npx convex insights shows high bytes or documents read, OCC conflict errors or mutation retries appear, subscriptions or UI updates are costly, functions hit execution or transaction limits, or the user mentions performance, latency, read amplification, or invalidation problems in a Convex app.4---5 6# Convex Performance Audit7 8Diagnose and fix performance problems in Convex applications, one problem class at a time.9 10## When to Use11 12- A Convex page or feature feels slow or expensive13- `npx convex insights --details` reports high bytes read, documents read, or OCC conflicts14- Low-freshness read paths are using reactivity where point-in-time reads would do15- OCC conflict errors or excessive mutation retries16- High subscription count or slow UI updates17- Functions approaching execution or transaction limits18- The same performance pattern needs fixing across sibling functions19 20## When Not to Use21 22- Initial Convex setup, auth setup, or component extraction23- Pure schema migrations with no performance goal24- One-off micro-optimizations without a user-visible or deployment-visible problem25 26## Guardrails27 28- Prefer simpler code when scale is small, traffic is modest, or the available signals are weak29- 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 path30- 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 scale31 32## First Step: Gather Signals33 34Start with the strongest signal available:35 361. If deployment Health insights are already available from the user or the current context, treat them as a first-class source of performance signals.372. If CLI insights are available, run `npx convex insights --details`. Use `--prod`, `--preview-name`, or `--deployment-name` when needed.38   - If the local repo's Convex CLI is too old to support `insights`, try `npx -y convex@latest insights --details` before giving up.393. 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.404. 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.41 42## Signal Routing43 44After gathering signals, identify the problem class and read the matching reference file.45 46| Signal                                                         | Reference                                 |47| -------------------------------------------------------------- | ----------------------------------------- |48| High bytes or documents read, JS filtering, unnecessary joins  | `references/hot-path-rules.md`            |49| OCC conflict errors, write contention, mutation retries        | `references/occ-conflicts.md`             |50| High subscription count, slow UI updates, excessive re-renders | `references/subscription-cost.md`         |51| Function timeouts, transaction size errors, large payloads     | `references/function-budget.md`           |52| General "it's slow" with no specific signal                    | Start with `references/hot-path-rules.md` |53 54Multiple problem classes can overlap. Read the most relevant reference first, then check the others if symptoms remain.55 56## Escalate Larger Fixes57 58If the likely fix is invasive, cross-cutting, or migration-heavy, stop and present options before editing.59 60Examples:61 62- introducing digest or summary tables across multiple flows63- splitting documents to isolate frequently-updated fields64- reworking pagination or fetch strategy across several screens65- switching to a new index or denormalized field that needs migration-safe rollout66 67When correctness depends on handling old and new states during a rollout, consult `skills/convex-migration-helper/SKILL.md` for the migration workflow.68 69## Workflow70 71### 1. Scope the problem72 73Pick one concrete user flow from the actual project. Look at the codebase, client pages, and API surface to find the flow that matches the symptom.74 75Write down:76 77- entrypoint functions78- client callsites using `useQuery`, `usePaginatedQuery`, or `useMutation`79- tables read80- tables written81- whether the path is high-read, high-write, or both82 83### 2. Trace the full read and write set84 85For each function in the path:86 871. Trace every `ctx.db.get()` and `ctx.db.query()`882. Trace every `ctx.db.patch()`, `ctx.db.replace()`, and `ctx.db.insert()`893. Note foreign-key lookups, JS-side filtering, and full-document reads904. Identify all sibling functions touching the same tables915. Identify reactive stats, aggregates, or widgets rendered on the same page92 93In Convex, every extra read increases transaction work, and every write can invalidate reactive subscribers. Treat read amplification and invalidation amplification as first-class problems.94 95### 3. Apply fixes from the relevant reference96 97Read the reference file matching your problem class. Each reference includes specific patterns, code examples, and a recommended fix order.98 99Do not stop at the single function named by an insight. Trace sibling readers and writers touching the same tables.100 101### 4. Fix sibling functions together102 103When one function touching a table has a performance bug, audit sibling functions for the same pattern.104 105After finding one problem, inspect both sibling readers and sibling writers for the same table family, including companion digest or summary tables.106 107Examples:108 109- If one list query switches from full docs to a digest table, inspect the other list queries for that table110- If one mutation isolates a frequently-updated field or splits a hot document, inspect the other writers to the same table111- If one read path needs a migration-safe rollout for an unbackfilled field, inspect sibling reads for the same rollout risk112 113Do not leave one path fixed and another path on the old pattern unless there is a clear product reason.114 115### 5. Verify before finishing116 117Confirm all of these:118 1191. Results are the same as before, no dropped records1202. Eliminated reads or writes are no longer in the path where expected1213. Fallback behavior works when denormalized or indexed fields are missing1224. Frequently-updated fields are isolated from widely-read documents where needed1235. Every relevant sibling reader and writer was inspected, not just the original function124 125## Reference Files126 127- `references/hot-path-rules.md` - Read amplification, invalidation, denormalization, indexes, digest tables128- `references/occ-conflicts.md` - Write contention, OCC resolution, hot document splitting129- `references/subscription-cost.md` - Reactive query cost, subscription granularity, point-in-time reads130- `references/function-budget.md` - Execution limits, transaction size, large documents, payload size131 132Also check the official [Convex Best Practices](https://docs.convex.dev/understanding/best-practices/) page for additional patterns covering argument validation, access control, and code organization that may surface during the audit.133 134## Checklist135 136- [ ] Gathered signals from insights, dashboard, or code audit137- [ ] Identified the problem class and read the matching reference138- [ ] Scoped one concrete user flow or function path139- [ ] Traced every read and write in that path140- [ ] Identified sibling functions touching the same tables141- [ ] Applied fixes from the reference, following the recommended fix order142- [ ] Fixed sibling functions consistently143- [ ] Verified behavior and confirmed no regressions