[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-convex-convex-performance-audit":3,"mdc-jhu7lx-key":35,"related-repo-convex-convex-performance-audit":835,"related-org-convex-convex-performance-audit":919},{"slug":4,"name":4,"fn":5,"description":6,"org":7,"tags":12,"stars":24,"repoUrl":25,"updatedAt":26,"license":27,"forks":28,"topics":29,"repo":30,"sourceUrl":33,"mdContent":34},"convex-performance-audit","audit Convex application performance","Audits Convex performance for reads, subscriptions, write contention, and function limits. Use for slow features, insights findings, OCC conflicts, or read amplification.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},"convex","Convex","https:\u002F\u002Fpexgzepcugksgbtrxkhf.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Forg-logos\u002Fconvex.png","get-convex",[13,17,18,21],{"name":14,"slug":15,"type":16},"Performance","performance","tag",{"name":9,"slug":8,"type":16},{"name":19,"slug":20,"type":16},"Monitoring","monitoring",{"name":22,"slug":23,"type":16},"Debugging","debugging",34,"https:\u002F\u002Fgithub.com\u002Fget-convex\u002Fagent-skills","2026-07-12T08:00:50.02928",null,7,[],{"repoUrl":25,"stars":24,"forks":28,"topics":31,"description":32},[],"Convex Skills for Agents","https:\u002F\u002Fgithub.com\u002Fget-convex\u002Fagent-skills\u002Ftree\u002FHEAD\u002Fskills\u002Fconvex-performance-audit","---\nname: convex-performance-audit\ndescription:\n  Audits Convex performance for reads, subscriptions, write contention, and\n  function limits. Use for slow features, insights findings, OCC conflicts, or\n  read amplification.\n---\n\n# Convex Performance Audit\n\nDiagnose and fix performance problems in Convex applications, one problem class\nat a time.\n\n## When to Use\n\n- A Convex page or feature feels slow or expensive\n- `npx convex insights --details` reports high bytes read, documents read, or\n  OCC conflicts\n- Low-freshness read paths are using reactivity where point-in-time reads would\n  do\n- OCC conflict errors or excessive mutation retries\n- High subscription count or slow UI updates\n- Functions approaching execution or transaction limits\n- The same performance pattern needs fixing across sibling functions\n\n## When Not to Use\n\n- Initial Convex setup, auth setup, or component extraction\n- Pure schema migrations with no performance goal\n- One-off micro-optimizations without a user-visible or deployment-visible\n  problem\n\n## Guardrails\n\n- Prefer simpler code when scale is small, traffic is modest, or the available\n  signals are weak\n- Do not recommend digest tables, document splitting, fetch-strategy changes, or\n  migration-heavy rollouts unless there is a measured signal, a clearly\n  unbounded path, or a known hot read\u002Fwrite path\n- In Convex, a simple scan on a small table is often acceptable. Do not invent\n  structural work just because a pattern is not ideal at large scale\n\n## First Step: Gather Signals\n\nStart with the strongest signal available:\n\n1. If deployment Health insights are already available from the user or the\n   current context, treat them as a first-class source of performance signals.\n2. If CLI insights are available, run `npx convex insights --details`. Use\n   `--prod`, `--preview-name`, or `--deployment-name` when needed.\n   - If the local repo's Convex CLI is too old to support `insights`, try\n     `npx -y convex@latest insights --details` before giving up.\n3. If the repo already uses `convex-doctor`, you may treat its findings as\n   hints. Do not require it, and do not treat it as the source of truth.\n4. If runtime signals are unavailable, audit from code anyway, but keep the\n   guardrails above in mind. Lack of insights is not proof of health, but it is\n   also not proof that a large refactor is warranted.\n\n## Signal Routing\n\nAfter gathering signals, identify the problem class and read the matching\nreference file.\n\n| Signal                                                         | Reference                                 |\n| -------------------------------------------------------------- | ----------------------------------------- |\n| High bytes or documents read, JS filtering, unnecessary joins  | `references\u002Fhot-path-rules.md`            |\n| OCC conflict errors, write contention, mutation retries        | `references\u002Focc-conflicts.md`             |\n| High subscription count, slow UI updates, excessive re-renders | `references\u002Fsubscription-cost.md`         |\n| Function timeouts, transaction size errors, large payloads     | `references\u002Ffunction-budget.md`           |\n| General \"it's slow\" with no specific signal                    | Start with `references\u002Fhot-path-rules.md` |\n\nMultiple problem classes can overlap. Read the most relevant reference first,\nthen check the others if symptoms remain.\n\n## Escalate Larger Fixes\n\nIf the likely fix is invasive, cross-cutting, or migration-heavy, stop and\npresent options before editing.\n\nExamples:\n\n- introducing digest or summary tables across multiple flows\n- splitting documents to isolate frequently-updated fields\n- reworking pagination or fetch strategy across several screens\n- switching to a new index or denormalized field that needs migration-safe\n  rollout\n\nWhen correctness depends on handling old and new states during a rollout,\nconsult the `convex-migration-helper` skill for the migration workflow.\n\n## Workflow\n\n### 1. Scope the problem\n\nPick one concrete user flow from the actual project. Look at the codebase,\nclient pages, and API surface to find the flow that matches the symptom.\n\nWrite down:\n\n- entrypoint functions\n- client callsites using `useQuery`, `usePaginatedQuery`, or `useMutation`\n- tables read\n- tables written\n- whether the path is high-read, high-write, or both\n\n### 2. Trace the full read and write set\n\nFor each function in the path:\n\n1. Trace every `ctx.db.get()` and `ctx.db.query()`\n2. Trace every `ctx.db.patch()`, `ctx.db.replace()`, and `ctx.db.insert()`\n3. Note foreign-key lookups, JS-side filtering, and full-document reads\n4. Identify all sibling functions touching the same tables\n5. Identify reactive stats, aggregates, or widgets rendered on the same page\n\nIn Convex, every extra read increases transaction work, and every write can\ninvalidate reactive subscribers. Treat read amplification and invalidation\namplification as first-class problems.\n\n### 3. Apply fixes from the relevant reference\n\nRead the reference file matching your problem class. Each reference includes\nspecific patterns, code examples, and a recommended fix order.\n\nDo not stop at the single function named by an insight. Trace sibling readers\nand writers touching the same tables.\n\n### 4. Fix sibling functions together\n\nWhen one function touching a table has a performance bug, audit sibling\nfunctions for the same pattern.\n\nAfter finding one problem, inspect both sibling readers and sibling writers for\nthe same table family, including companion digest or summary tables.\n\nExamples:\n\n- If one list query switches from full docs to a digest table, inspect the other\n  list queries for that table\n- If one mutation isolates a frequently-updated field or splits a hot document,\n  inspect the other writers to the same table\n- If one read path needs a migration-safe rollout for an unbackfilled field,\n  inspect sibling reads for the same rollout risk\n\nDo not leave one path fixed and another path on the old pattern unless there is\na clear product reason.\n\n### 5. Verify before finishing\n\nConfirm all of these:\n\n1. Results are the same as before, no dropped records\n2. Eliminated reads or writes are no longer in the path where expected\n3. Fallback behavior works when denormalized or indexed fields are missing\n4. Frequently-updated fields are isolated from widely-read documents where\n   needed\n5. Every relevant sibling reader and writer was inspected, not just the original\n   function\n\n## Reference Files\n\n- `references\u002Fhot-path-rules.md` - Read amplification, invalidation,\n  denormalization, indexes, digest tables\n- `references\u002Focc-conflicts.md` - Write contention, OCC resolution, hot document\n  splitting\n- `references\u002Fsubscription-cost.md` - Reactive query cost, subscription\n  granularity, point-in-time reads\n- `references\u002Ffunction-budget.md` - Execution limits, transaction size, large\n  documents, payload size\n\nAlso check the official\n[Convex Best Practices](https:\u002F\u002Fdocs.convex.dev\u002Funderstanding\u002Fbest-practices\u002F)\npage for additional patterns covering argument validation, access control, and\ncode organization that may surface during the audit.\n\n## Checklist\n\n- [ ] Gathered signals from insights, dashboard, or code audit\n- [ ] Identified the problem class and read the matching reference\n- [ ] Scoped one concrete user flow or function path\n- [ ] Traced every read and write in that path\n- [ ] Identified sibling functions touching the same tables\n- [ ] Applied fixes from the reference, following the recommended fix order\n- [ ] Fixed sibling functions consistently\n- [ ] Verified behavior and confirmed no regressions\n",{"data":36,"body":37},{"name":4,"description":6},{"type":38,"children":39},"root",[40,48,54,61,108,114,132,138,156,162,167,254,260,265,379,384,390,395,400,423,436,442,449,454,459,507,513,518,580,585,591,596,601,607,612,617,621,639,644,650,655,683,689,732,748,754],{"type":41,"tag":42,"props":43,"children":44},"element","h1",{"id":4},[45],{"type":46,"value":47},"text","Convex Performance Audit",{"type":41,"tag":49,"props":50,"children":51},"p",{},[52],{"type":46,"value":53},"Diagnose and fix performance problems in Convex applications, one problem class\nat a time.",{"type":41,"tag":55,"props":56,"children":58},"h2",{"id":57},"when-to-use",[59],{"type":46,"value":60},"When to Use",{"type":41,"tag":62,"props":63,"children":64},"ul",{},[65,71,83,88,93,98,103],{"type":41,"tag":66,"props":67,"children":68},"li",{},[69],{"type":46,"value":70},"A Convex page or feature feels slow or expensive",{"type":41,"tag":66,"props":72,"children":73},{},[74,81],{"type":41,"tag":75,"props":76,"children":78},"code",{"className":77},[],[79],{"type":46,"value":80},"npx convex insights --details",{"type":46,"value":82}," reports high bytes read, documents read, or\nOCC conflicts",{"type":41,"tag":66,"props":84,"children":85},{},[86],{"type":46,"value":87},"Low-freshness read paths are using reactivity where point-in-time reads would\ndo",{"type":41,"tag":66,"props":89,"children":90},{},[91],{"type":46,"value":92},"OCC conflict errors or excessive mutation retries",{"type":41,"tag":66,"props":94,"children":95},{},[96],{"type":46,"value":97},"High subscription count or slow UI updates",{"type":41,"tag":66,"props":99,"children":100},{},[101],{"type":46,"value":102},"Functions approaching execution or transaction limits",{"type":41,"tag":66,"props":104,"children":105},{},[106],{"type":46,"value":107},"The same performance pattern needs fixing across sibling functions",{"type":41,"tag":55,"props":109,"children":111},{"id":110},"when-not-to-use",[112],{"type":46,"value":113},"When Not to Use",{"type":41,"tag":62,"props":115,"children":116},{},[117,122,127],{"type":41,"tag":66,"props":118,"children":119},{},[120],{"type":46,"value":121},"Initial Convex setup, auth setup, or component extraction",{"type":41,"tag":66,"props":123,"children":124},{},[125],{"type":46,"value":126},"Pure schema migrations with no performance goal",{"type":41,"tag":66,"props":128,"children":129},{},[130],{"type":46,"value":131},"One-off micro-optimizations without a user-visible or deployment-visible\nproblem",{"type":41,"tag":55,"props":133,"children":135},{"id":134},"guardrails",[136],{"type":46,"value":137},"Guardrails",{"type":41,"tag":62,"props":139,"children":140},{},[141,146,151],{"type":41,"tag":66,"props":142,"children":143},{},[144],{"type":46,"value":145},"Prefer simpler code when scale is small, traffic is modest, or the available\nsignals are weak",{"type":41,"tag":66,"props":147,"children":148},{},[149],{"type":46,"value":150},"Do not recommend digest tables, document splitting, fetch-strategy changes, or\nmigration-heavy rollouts unless there is a measured signal, a clearly\nunbounded path, or a known hot read\u002Fwrite path",{"type":41,"tag":66,"props":152,"children":153},{},[154],{"type":46,"value":155},"In Convex, a simple scan on a small table is often acceptable. Do not invent\nstructural work just because a pattern is not ideal at large scale",{"type":41,"tag":55,"props":157,"children":159},{"id":158},"first-step-gather-signals",[160],{"type":46,"value":161},"First Step: Gather Signals",{"type":41,"tag":49,"props":163,"children":164},{},[165],{"type":46,"value":166},"Start with the strongest signal available:",{"type":41,"tag":168,"props":169,"children":170},"ol",{},[171,176,236,249],{"type":41,"tag":66,"props":172,"children":173},{},[174],{"type":46,"value":175},"If deployment Health insights are already available from the user or the\ncurrent context, treat them as a first-class source of performance signals.",{"type":41,"tag":66,"props":177,"children":178},{},[179,181,186,188,194,196,202,204,210,212],{"type":46,"value":180},"If CLI insights are available, run ",{"type":41,"tag":75,"props":182,"children":184},{"className":183},[],[185],{"type":46,"value":80},{"type":46,"value":187},". Use\n",{"type":41,"tag":75,"props":189,"children":191},{"className":190},[],[192],{"type":46,"value":193},"--prod",{"type":46,"value":195},", ",{"type":41,"tag":75,"props":197,"children":199},{"className":198},[],[200],{"type":46,"value":201},"--preview-name",{"type":46,"value":203},", or ",{"type":41,"tag":75,"props":205,"children":207},{"className":206},[],[208],{"type":46,"value":209},"--deployment-name",{"type":46,"value":211}," when needed.\n",{"type":41,"tag":62,"props":213,"children":214},{},[215],{"type":41,"tag":66,"props":216,"children":217},{},[218,220,226,228,234],{"type":46,"value":219},"If the local repo's Convex CLI is too old to support ",{"type":41,"tag":75,"props":221,"children":223},{"className":222},[],[224],{"type":46,"value":225},"insights",{"type":46,"value":227},", try\n",{"type":41,"tag":75,"props":229,"children":231},{"className":230},[],[232],{"type":46,"value":233},"npx -y convex@latest insights --details",{"type":46,"value":235}," before giving up.",{"type":41,"tag":66,"props":237,"children":238},{},[239,241,247],{"type":46,"value":240},"If the repo already uses ",{"type":41,"tag":75,"props":242,"children":244},{"className":243},[],[245],{"type":46,"value":246},"convex-doctor",{"type":46,"value":248},", you may treat its findings as\nhints. Do not require it, and do not treat it as the source of truth.",{"type":41,"tag":66,"props":250,"children":251},{},[252],{"type":46,"value":253},"If runtime signals are unavailable, audit from code anyway, but keep the\nguardrails above in mind. Lack of insights is not proof of health, but it is\nalso not proof that a large refactor is warranted.",{"type":41,"tag":55,"props":255,"children":257},{"id":256},"signal-routing",[258],{"type":46,"value":259},"Signal Routing",{"type":41,"tag":49,"props":261,"children":262},{},[263],{"type":46,"value":264},"After gathering signals, identify the problem class and read the matching\nreference file.",{"type":41,"tag":266,"props":267,"children":268},"table",{},[269,288],{"type":41,"tag":270,"props":271,"children":272},"thead",{},[273],{"type":41,"tag":274,"props":275,"children":276},"tr",{},[277,283],{"type":41,"tag":278,"props":279,"children":280},"th",{},[281],{"type":46,"value":282},"Signal",{"type":41,"tag":278,"props":284,"children":285},{},[286],{"type":46,"value":287},"Reference",{"type":41,"tag":289,"props":290,"children":291},"tbody",{},[292,310,327,344,361],{"type":41,"tag":274,"props":293,"children":294},{},[295,301],{"type":41,"tag":296,"props":297,"children":298},"td",{},[299],{"type":46,"value":300},"High bytes or documents read, JS filtering, unnecessary joins",{"type":41,"tag":296,"props":302,"children":303},{},[304],{"type":41,"tag":75,"props":305,"children":307},{"className":306},[],[308],{"type":46,"value":309},"references\u002Fhot-path-rules.md",{"type":41,"tag":274,"props":311,"children":312},{},[313,318],{"type":41,"tag":296,"props":314,"children":315},{},[316],{"type":46,"value":317},"OCC conflict errors, write contention, mutation retries",{"type":41,"tag":296,"props":319,"children":320},{},[321],{"type":41,"tag":75,"props":322,"children":324},{"className":323},[],[325],{"type":46,"value":326},"references\u002Focc-conflicts.md",{"type":41,"tag":274,"props":328,"children":329},{},[330,335],{"type":41,"tag":296,"props":331,"children":332},{},[333],{"type":46,"value":334},"High subscription count, slow UI updates, excessive re-renders",{"type":41,"tag":296,"props":336,"children":337},{},[338],{"type":41,"tag":75,"props":339,"children":341},{"className":340},[],[342],{"type":46,"value":343},"references\u002Fsubscription-cost.md",{"type":41,"tag":274,"props":345,"children":346},{},[347,352],{"type":41,"tag":296,"props":348,"children":349},{},[350],{"type":46,"value":351},"Function timeouts, transaction size errors, large payloads",{"type":41,"tag":296,"props":353,"children":354},{},[355],{"type":41,"tag":75,"props":356,"children":358},{"className":357},[],[359],{"type":46,"value":360},"references\u002Ffunction-budget.md",{"type":41,"tag":274,"props":362,"children":363},{},[364,369],{"type":41,"tag":296,"props":365,"children":366},{},[367],{"type":46,"value":368},"General \"it's slow\" with no specific signal",{"type":41,"tag":296,"props":370,"children":371},{},[372,374],{"type":46,"value":373},"Start with ",{"type":41,"tag":75,"props":375,"children":377},{"className":376},[],[378],{"type":46,"value":309},{"type":41,"tag":49,"props":380,"children":381},{},[382],{"type":46,"value":383},"Multiple problem classes can overlap. Read the most relevant reference first,\nthen check the others if symptoms remain.",{"type":41,"tag":55,"props":385,"children":387},{"id":386},"escalate-larger-fixes",[388],{"type":46,"value":389},"Escalate Larger Fixes",{"type":41,"tag":49,"props":391,"children":392},{},[393],{"type":46,"value":394},"If the likely fix is invasive, cross-cutting, or migration-heavy, stop and\npresent options before editing.",{"type":41,"tag":49,"props":396,"children":397},{},[398],{"type":46,"value":399},"Examples:",{"type":41,"tag":62,"props":401,"children":402},{},[403,408,413,418],{"type":41,"tag":66,"props":404,"children":405},{},[406],{"type":46,"value":407},"introducing digest or summary tables across multiple flows",{"type":41,"tag":66,"props":409,"children":410},{},[411],{"type":46,"value":412},"splitting documents to isolate frequently-updated fields",{"type":41,"tag":66,"props":414,"children":415},{},[416],{"type":46,"value":417},"reworking pagination or fetch strategy across several screens",{"type":41,"tag":66,"props":419,"children":420},{},[421],{"type":46,"value":422},"switching to a new index or denormalized field that needs migration-safe\nrollout",{"type":41,"tag":49,"props":424,"children":425},{},[426,428,434],{"type":46,"value":427},"When correctness depends on handling old and new states during a rollout,\nconsult the ",{"type":41,"tag":75,"props":429,"children":431},{"className":430},[],[432],{"type":46,"value":433},"convex-migration-helper",{"type":46,"value":435}," skill for the migration workflow.",{"type":41,"tag":55,"props":437,"children":439},{"id":438},"workflow",[440],{"type":46,"value":441},"Workflow",{"type":41,"tag":443,"props":444,"children":446},"h3",{"id":445},"_1-scope-the-problem",[447],{"type":46,"value":448},"1. Scope the problem",{"type":41,"tag":49,"props":450,"children":451},{},[452],{"type":46,"value":453},"Pick one concrete user flow from the actual project. Look at the codebase,\nclient pages, and API surface to find the flow that matches the symptom.",{"type":41,"tag":49,"props":455,"children":456},{},[457],{"type":46,"value":458},"Write down:",{"type":41,"tag":62,"props":460,"children":461},{},[462,467,492,497,502],{"type":41,"tag":66,"props":463,"children":464},{},[465],{"type":46,"value":466},"entrypoint functions",{"type":41,"tag":66,"props":468,"children":469},{},[470,472,478,479,485,486],{"type":46,"value":471},"client callsites using ",{"type":41,"tag":75,"props":473,"children":475},{"className":474},[],[476],{"type":46,"value":477},"useQuery",{"type":46,"value":195},{"type":41,"tag":75,"props":480,"children":482},{"className":481},[],[483],{"type":46,"value":484},"usePaginatedQuery",{"type":46,"value":203},{"type":41,"tag":75,"props":487,"children":489},{"className":488},[],[490],{"type":46,"value":491},"useMutation",{"type":41,"tag":66,"props":493,"children":494},{},[495],{"type":46,"value":496},"tables read",{"type":41,"tag":66,"props":498,"children":499},{},[500],{"type":46,"value":501},"tables written",{"type":41,"tag":66,"props":503,"children":504},{},[505],{"type":46,"value":506},"whether the path is high-read, high-write, or both",{"type":41,"tag":443,"props":508,"children":510},{"id":509},"_2-trace-the-full-read-and-write-set",[511],{"type":46,"value":512},"2. Trace the full read and write set",{"type":41,"tag":49,"props":514,"children":515},{},[516],{"type":46,"value":517},"For each function in the path:",{"type":41,"tag":168,"props":519,"children":520},{},[521,540,565,570,575],{"type":41,"tag":66,"props":522,"children":523},{},[524,526,532,534],{"type":46,"value":525},"Trace every ",{"type":41,"tag":75,"props":527,"children":529},{"className":528},[],[530],{"type":46,"value":531},"ctx.db.get()",{"type":46,"value":533}," and ",{"type":41,"tag":75,"props":535,"children":537},{"className":536},[],[538],{"type":46,"value":539},"ctx.db.query()",{"type":41,"tag":66,"props":541,"children":542},{},[543,544,550,551,557,559],{"type":46,"value":525},{"type":41,"tag":75,"props":545,"children":547},{"className":546},[],[548],{"type":46,"value":549},"ctx.db.patch()",{"type":46,"value":195},{"type":41,"tag":75,"props":552,"children":554},{"className":553},[],[555],{"type":46,"value":556},"ctx.db.replace()",{"type":46,"value":558},", and ",{"type":41,"tag":75,"props":560,"children":562},{"className":561},[],[563],{"type":46,"value":564},"ctx.db.insert()",{"type":41,"tag":66,"props":566,"children":567},{},[568],{"type":46,"value":569},"Note foreign-key lookups, JS-side filtering, and full-document reads",{"type":41,"tag":66,"props":571,"children":572},{},[573],{"type":46,"value":574},"Identify all sibling functions touching the same tables",{"type":41,"tag":66,"props":576,"children":577},{},[578],{"type":46,"value":579},"Identify reactive stats, aggregates, or widgets rendered on the same page",{"type":41,"tag":49,"props":581,"children":582},{},[583],{"type":46,"value":584},"In Convex, every extra read increases transaction work, and every write can\ninvalidate reactive subscribers. Treat read amplification and invalidation\namplification as first-class problems.",{"type":41,"tag":443,"props":586,"children":588},{"id":587},"_3-apply-fixes-from-the-relevant-reference",[589],{"type":46,"value":590},"3. Apply fixes from the relevant reference",{"type":41,"tag":49,"props":592,"children":593},{},[594],{"type":46,"value":595},"Read the reference file matching your problem class. Each reference includes\nspecific patterns, code examples, and a recommended fix order.",{"type":41,"tag":49,"props":597,"children":598},{},[599],{"type":46,"value":600},"Do not stop at the single function named by an insight. Trace sibling readers\nand writers touching the same tables.",{"type":41,"tag":443,"props":602,"children":604},{"id":603},"_4-fix-sibling-functions-together",[605],{"type":46,"value":606},"4. Fix sibling functions together",{"type":41,"tag":49,"props":608,"children":609},{},[610],{"type":46,"value":611},"When one function touching a table has a performance bug, audit sibling\nfunctions for the same pattern.",{"type":41,"tag":49,"props":613,"children":614},{},[615],{"type":46,"value":616},"After finding one problem, inspect both sibling readers and sibling writers for\nthe same table family, including companion digest or summary tables.",{"type":41,"tag":49,"props":618,"children":619},{},[620],{"type":46,"value":399},{"type":41,"tag":62,"props":622,"children":623},{},[624,629,634],{"type":41,"tag":66,"props":625,"children":626},{},[627],{"type":46,"value":628},"If one list query switches from full docs to a digest table, inspect the other\nlist queries for that table",{"type":41,"tag":66,"props":630,"children":631},{},[632],{"type":46,"value":633},"If one mutation isolates a frequently-updated field or splits a hot document,\ninspect the other writers to the same table",{"type":41,"tag":66,"props":635,"children":636},{},[637],{"type":46,"value":638},"If one read path needs a migration-safe rollout for an unbackfilled field,\ninspect sibling reads for the same rollout risk",{"type":41,"tag":49,"props":640,"children":641},{},[642],{"type":46,"value":643},"Do not leave one path fixed and another path on the old pattern unless there is\na clear product reason.",{"type":41,"tag":443,"props":645,"children":647},{"id":646},"_5-verify-before-finishing",[648],{"type":46,"value":649},"5. Verify before finishing",{"type":41,"tag":49,"props":651,"children":652},{},[653],{"type":46,"value":654},"Confirm all of these:",{"type":41,"tag":168,"props":656,"children":657},{},[658,663,668,673,678],{"type":41,"tag":66,"props":659,"children":660},{},[661],{"type":46,"value":662},"Results are the same as before, no dropped records",{"type":41,"tag":66,"props":664,"children":665},{},[666],{"type":46,"value":667},"Eliminated reads or writes are no longer in the path where expected",{"type":41,"tag":66,"props":669,"children":670},{},[671],{"type":46,"value":672},"Fallback behavior works when denormalized or indexed fields are missing",{"type":41,"tag":66,"props":674,"children":675},{},[676],{"type":46,"value":677},"Frequently-updated fields are isolated from widely-read documents where\nneeded",{"type":41,"tag":66,"props":679,"children":680},{},[681],{"type":46,"value":682},"Every relevant sibling reader and writer was inspected, not just the original\nfunction",{"type":41,"tag":55,"props":684,"children":686},{"id":685},"reference-files",[687],{"type":46,"value":688},"Reference Files",{"type":41,"tag":62,"props":690,"children":691},{},[692,702,712,722],{"type":41,"tag":66,"props":693,"children":694},{},[695,700],{"type":41,"tag":75,"props":696,"children":698},{"className":697},[],[699],{"type":46,"value":309},{"type":46,"value":701}," - Read amplification, invalidation,\ndenormalization, indexes, digest tables",{"type":41,"tag":66,"props":703,"children":704},{},[705,710],{"type":41,"tag":75,"props":706,"children":708},{"className":707},[],[709],{"type":46,"value":326},{"type":46,"value":711}," - Write contention, OCC resolution, hot document\nsplitting",{"type":41,"tag":66,"props":713,"children":714},{},[715,720],{"type":41,"tag":75,"props":716,"children":718},{"className":717},[],[719],{"type":46,"value":343},{"type":46,"value":721}," - Reactive query cost, subscription\ngranularity, point-in-time reads",{"type":41,"tag":66,"props":723,"children":724},{},[725,730],{"type":41,"tag":75,"props":726,"children":728},{"className":727},[],[729],{"type":46,"value":360},{"type":46,"value":731}," - Execution limits, transaction size, large\ndocuments, payload size",{"type":41,"tag":49,"props":733,"children":734},{},[735,737,746],{"type":46,"value":736},"Also check the official\n",{"type":41,"tag":738,"props":739,"children":743},"a",{"href":740,"rel":741},"https:\u002F\u002Fdocs.convex.dev\u002Funderstanding\u002Fbest-practices\u002F",[742],"nofollow",[744],{"type":46,"value":745},"Convex Best Practices",{"type":46,"value":747},"\npage for additional patterns covering argument validation, access control, and\ncode organization that may surface during the audit.",{"type":41,"tag":55,"props":749,"children":751},{"id":750},"checklist",[752],{"type":46,"value":753},"Checklist",{"type":41,"tag":62,"props":755,"children":758},{"className":756},[757],"contains-task-list",[759,772,781,790,799,808,817,826],{"type":41,"tag":66,"props":760,"children":763},{"className":761},[762],"task-list-item",[764,770],{"type":41,"tag":765,"props":766,"children":769},"input",{"disabled":767,"type":768},true,"checkbox",[],{"type":46,"value":771}," Gathered signals from insights, dashboard, or code audit",{"type":41,"tag":66,"props":773,"children":775},{"className":774},[762],[776,779],{"type":41,"tag":765,"props":777,"children":778},{"disabled":767,"type":768},[],{"type":46,"value":780}," Identified the problem class and read the matching reference",{"type":41,"tag":66,"props":782,"children":784},{"className":783},[762],[785,788],{"type":41,"tag":765,"props":786,"children":787},{"disabled":767,"type":768},[],{"type":46,"value":789}," Scoped one concrete user flow or function path",{"type":41,"tag":66,"props":791,"children":793},{"className":792},[762],[794,797],{"type":41,"tag":765,"props":795,"children":796},{"disabled":767,"type":768},[],{"type":46,"value":798}," Traced every read and write in that path",{"type":41,"tag":66,"props":800,"children":802},{"className":801},[762],[803,806],{"type":41,"tag":765,"props":804,"children":805},{"disabled":767,"type":768},[],{"type":46,"value":807}," Identified sibling functions touching the same tables",{"type":41,"tag":66,"props":809,"children":811},{"className":810},[762],[812,815],{"type":41,"tag":765,"props":813,"children":814},{"disabled":767,"type":768},[],{"type":46,"value":816}," Applied fixes from the reference, following the recommended fix order",{"type":41,"tag":66,"props":818,"children":820},{"className":819},[762],[821,824],{"type":41,"tag":765,"props":822,"children":823},{"disabled":767,"type":768},[],{"type":46,"value":825}," Fixed sibling functions consistently",{"type":41,"tag":66,"props":827,"children":829},{"className":828},[762],[830,833],{"type":41,"tag":765,"props":831,"children":832},{"disabled":767,"type":768},[],{"type":46,"value":834}," Verified behavior and confirmed no regressions",{"items":836,"total":918},[837,850,865,879,886,903],{"slug":8,"name":8,"fn":838,"description":839,"org":840,"tags":841,"stars":24,"repoUrl":25,"updatedAt":849},"guide Convex project setup and usage","Routes general Convex requests to the right project skill. Use when the user asks which Convex skill to use or gives an underspecified Convex app task.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[842,845,846],{"name":843,"slug":844,"type":16},"Backend","backend",{"name":9,"slug":8,"type":16},{"name":847,"slug":848,"type":16},"Database","database","2026-07-12T08:00:45.091281",{"slug":851,"name":851,"fn":852,"description":853,"org":854,"tags":855,"stars":24,"repoUrl":25,"updatedAt":864},"convex-create-component","build reusable Convex components","Builds reusable Convex components with isolated tables and app-facing APIs. Use for new components, reusable backend modules, integrations, or component boundary work.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[856,859,862,863],{"name":857,"slug":858,"type":16},"API Development","api-development",{"name":860,"slug":861,"type":16},"Architecture","architecture",{"name":843,"slug":844,"type":16},{"name":9,"slug":8,"type":16},"2026-07-12T08:00:39.428577",{"slug":433,"name":433,"fn":866,"description":867,"org":868,"tags":869,"stars":24,"repoUrl":25,"updatedAt":878},"plan Convex schema and data migrations","Plans Convex schema and data migrations with widen-migrate-narrow and @convex-dev\u002Fmigrations. Use for breaking schema changes, backfills, table reshaping, or zero-downtime rollouts.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[870,871,872,875],{"name":843,"slug":844,"type":16},{"name":9,"slug":8,"type":16},{"name":873,"slug":874,"type":16},"Data Engineering","data-engineering",{"name":876,"slug":877,"type":16},"Migration","migration","2026-07-12T08:00:51.27967",{"slug":4,"name":4,"fn":5,"description":6,"org":880,"tags":881,"stars":24,"repoUrl":25,"updatedAt":26},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[882,883,884,885],{"name":9,"slug":8,"type":16},{"name":22,"slug":23,"type":16},{"name":19,"slug":20,"type":16},{"name":14,"slug":15,"type":16},{"slug":887,"name":887,"fn":888,"description":889,"org":890,"tags":891,"stars":24,"repoUrl":25,"updatedAt":902},"convex-quickstart","initialize Convex in applications","Creates or adds Convex to an app. Use for new Convex projects, npm create convex@latest, frontend setup, env vars, or the first npx convex dev run.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[892,895,896,899],{"name":893,"slug":894,"type":16},"CLI","cli",{"name":9,"slug":8,"type":16},{"name":897,"slug":898,"type":16},"Frontend","frontend",{"name":900,"slug":901,"type":16},"Onboarding","onboarding","2026-07-12T08:00:43.436152",{"slug":904,"name":904,"fn":905,"description":906,"org":907,"tags":908,"stars":24,"repoUrl":25,"updatedAt":917},"convex-setup-auth","set up authentication and access control","Sets up Convex auth, identity mapping, and access control. Use for login, auth providers, users tables, protected functions, or roles in a Convex app.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[909,912,915,916],{"name":910,"slug":911,"type":16},"Access Control","access-control",{"name":913,"slug":914,"type":16},"Auth","auth",{"name":843,"slug":844,"type":16},{"name":9,"slug":8,"type":16},"2026-07-12T08:00:48.652641",6,{"items":920,"total":1055},[921,927,934,941,948,955,962,976,995,1009,1026,1040],{"slug":8,"name":8,"fn":838,"description":839,"org":922,"tags":923,"stars":24,"repoUrl":25,"updatedAt":849},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[924,925,926],{"name":843,"slug":844,"type":16},{"name":9,"slug":8,"type":16},{"name":847,"slug":848,"type":16},{"slug":851,"name":851,"fn":852,"description":853,"org":928,"tags":929,"stars":24,"repoUrl":25,"updatedAt":864},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[930,931,932,933],{"name":857,"slug":858,"type":16},{"name":860,"slug":861,"type":16},{"name":843,"slug":844,"type":16},{"name":9,"slug":8,"type":16},{"slug":433,"name":433,"fn":866,"description":867,"org":935,"tags":936,"stars":24,"repoUrl":25,"updatedAt":878},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[937,938,939,940],{"name":843,"slug":844,"type":16},{"name":9,"slug":8,"type":16},{"name":873,"slug":874,"type":16},{"name":876,"slug":877,"type":16},{"slug":4,"name":4,"fn":5,"description":6,"org":942,"tags":943,"stars":24,"repoUrl":25,"updatedAt":26},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[944,945,946,947],{"name":9,"slug":8,"type":16},{"name":22,"slug":23,"type":16},{"name":19,"slug":20,"type":16},{"name":14,"slug":15,"type":16},{"slug":887,"name":887,"fn":888,"description":889,"org":949,"tags":950,"stars":24,"repoUrl":25,"updatedAt":902},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[951,952,953,954],{"name":893,"slug":894,"type":16},{"name":9,"slug":8,"type":16},{"name":897,"slug":898,"type":16},{"name":900,"slug":901,"type":16},{"slug":904,"name":904,"fn":905,"description":906,"org":956,"tags":957,"stars":24,"repoUrl":25,"updatedAt":917},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[958,959,960,961],{"name":910,"slug":911,"type":16},{"name":913,"slug":914,"type":16},{"name":843,"slug":844,"type":16},{"name":9,"slug":8,"type":16},{"slug":963,"name":963,"fn":964,"description":965,"org":966,"tags":967,"stars":973,"repoUrl":974,"updatedAt":975},"add","add capabilities to Convex applications","Add a capability to the CURRENT Convex + Next.js project — consults the served Convex capability catalog for always-current procedures (billing, crons, auth, agent, search, …); falls back to built-in hosting or @convex-dev component search. TRIGGER when the user runs $add, or asks to add hosting\u002Fpublishing or any backend capability to an existing Convex app.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[968,969,970],{"name":843,"slug":844,"type":16},{"name":9,"slug":8,"type":16},{"name":971,"slug":972,"type":16},"Next.js","next-js",2,"https:\u002F\u002Fgithub.com\u002Fget-convex\u002Fconvex-codex-plugin","2026-07-12T07:59:59.358004",{"slug":977,"name":977,"fn":978,"description":979,"org":980,"tags":981,"stars":973,"repoUrl":974,"updatedAt":994},"agent","build AI agents with Convex","Build an AI agent \u002F RAG feature on Convex (@convex-dev\u002Fagent: threads, tools, vector search). TRIGGER on an AI-agent\u002Fchatbot\u002FRAG request.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[982,985,988,991],{"name":983,"slug":984,"type":16},"Agents","agents",{"name":986,"slug":987,"type":16},"Engineering","engineering",{"name":989,"slug":990,"type":16},"RAG","rag",{"name":992,"slug":993,"type":16},"Search","search","2026-07-12T08:00:01.921824",{"slug":914,"name":914,"fn":996,"description":997,"org":998,"tags":999,"stars":973,"repoUrl":974,"updatedAt":1008},"add authentication to Convex applications","Add sign-in (passkeys by default, OAuth\u002Fpassword optional) to the current Convex app, wired correctly incl. auth.config.ts. TRIGGER on a login\u002Fauth request for an existing app.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1000,1001,1004,1005],{"name":913,"slug":914,"type":16},{"name":1002,"slug":1003,"type":16},"Authentication","authentication",{"name":9,"slug":8,"type":16},{"name":1006,"slug":1007,"type":16},"OAuth","oauth","2026-07-18T05:12:54.443056",{"slug":1010,"name":1010,"fn":1011,"description":1012,"org":1013,"tags":1014,"stars":973,"repoUrl":974,"updatedAt":1025},"billing","integrate Stripe billing in Convex apps","Add Stripe billing to a Convex app via @convex-dev\u002Fstripe (checkout + auto-verified webhook + subscription gating). TRIGGER on a payments\u002Fbilling\u002Fsubscription request.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1015,1016,1019,1022],{"name":9,"slug":8,"type":16},{"name":1017,"slug":1018,"type":16},"Payments","payments",{"name":1020,"slug":1021,"type":16},"Stripe","stripe",{"name":1023,"slug":1024,"type":16},"Webhooks","webhooks","2026-07-12T08:00:08.123246",{"slug":1027,"name":1027,"fn":1028,"description":1029,"org":1030,"tags":1031,"stars":973,"repoUrl":974,"updatedAt":1039},"check-updates","upgrade Convex component versions","Check the CURRENT Convex app's pinned components against the latest recommended versions and offer to upgrade them — e.g. the passkey auth component's new email-first sign-in. TRIGGER when the user runs \u002Fcheck-updates or $check-updates, asks 'are my components up to date', 'any updates', 'upgrade auth', 'upgrade my components', or wants the newest features after a quickstart. Applies each upgrade behind a build gate (verify-or-revert) with the user's consent.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1032,1035,1036],{"name":1033,"slug":1034,"type":16},"Configuration","configuration",{"name":9,"slug":8,"type":16},{"name":1037,"slug":1038,"type":16},"Maintenance","maintenance","2026-07-12T08:00:03.236862",{"slug":1041,"name":1041,"fn":1042,"description":1043,"org":1044,"tags":1045,"stars":973,"repoUrl":974,"updatedAt":1054},"convex-authz","audit and harden Convex authorization","Audit and harden a Convex app's authorization: identity-from-arg impersonation, missing per-document ownership checks, and public queries leaking PII\u002Ffinancial data by a client-supplied id — the single largest real-defect cluster measured against generated Convex backends (44 of 214). Runs a deterministic scan for the 3 shapes, then applies the canonical requireIdentity\u002FrequireOwner pattern, then verifies with tsc. TRIGGER on 'secure my app', 'audit auth', 'add login', 'who can access this data', or an explicit 'audit my authz'. NOT always-on. SKIP when there is no convex\u002F directory.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1046,1047,1050,1051],{"name":913,"slug":914,"type":16},{"name":1048,"slug":1049,"type":16},"Code Analysis","code-analysis",{"name":9,"slug":8,"type":16},{"name":1052,"slug":1053,"type":16},"Security","security","2026-07-12T08:00:04.516752",26]