convex-performance-audit

Name: convex-performance-audit
Author: get-convex

89kinstalls8forks

How to install convex-performance-audit?

get-convex/agent-skills/convex-performance-audit

$npx -y skills add get-convex/agent-skills --skill convex-performance-audit

Installs into the current project.

Summary

Audits Convex performance for reads, subscriptions, write contention, and function limits. Use for slow features, insights findings, OCC conflicts, or read amplification.

Files · 1

View on GitHub

SKILL.md

1	# Convex Performance Audit
2
3	Diagnose and fix performance problems in Convex applications, one problem class
4	at a time.
5
6	## When to Use
7
8	- A Convex page or feature feels slow or expensive
9	- `npx convex insights --details` reports high bytes read, documents read, or
10	OCC conflicts
11	- Low-freshness read paths are using reactivity where point-in-time reads would
12	do
13	- OCC conflict errors or excessive mutation retries
14	- High subscription count or slow UI updates
15	- Functions approaching execution or transaction limits
16	- The same performance pattern needs fixing across sibling functions
17
18	## When Not to Use
19
20	- Initial Convex setup, auth setup, or component extraction
21	- Pure schema migrations with no performance goal
22	- One-off micro-optimizations without a user-visible or deployment-visible
23	problem
24
25	## Guardrails
26
27	- Prefer simpler code when scale is small, traffic is modest, or the available
28	signals are weak
29	- Do not recommend digest tables, document splitting, fetch-strategy changes, or
30	migration-heavy rollouts unless there is a measured signal, a clearly
31	unbounded path, or a known hot read/write path
32	- In Convex, a simple scan on a small table is often acceptable. Do not invent
33	structural work just because a pattern is not ideal at large scale
34
35	## First Step: Gather Signals
36
37	Start with the strongest signal available:
38
39	1. If deployment Health insights are already available from the user or the
40	current context, treat them as a first-class source of performance signals.
41	2. If CLI insights are available, run `npx convex insights --details`. Use
42	`--prod`, `--preview-name`, or `--deployment-name` when needed.
43	- If the local repo's Convex CLI is too old to support `insights`, try
44	`npx -y convex@latest insights --details` before giving up.
45	3. If the repo already uses `convex-doctor`, you may treat its findings as
46	hints. Do not require it, and do not treat it as the source of truth.
47	4. If runtime signals are unavailable, audit from code anyway, but keep the
48	guardrails above in mind. Lack of insights is not proof of health, but it is
49	also not proof that a large refactor is warranted.
50
51	## Signal Routing
52
53	After gathering signals, identify the problem class and read the matching
54	reference file.
55
56	\| Signal \| Reference \|
57	\| -------------------------------------------------------------- \| ----------------------------------------- \|
58	\| High bytes or documents read, JS filtering, unnecessary joins \| `references/hot-path-rules.md` \|
59	\| OCC conflict errors, write contention, mutation retries \| `references/occ-conflicts.md` \|
60	\| High subscription count, slow UI updates, excessive re-renders \| `references/subscription-cost.md` \|
61	\| Function timeouts, transaction size errors, large payloads \| `references/function-budget.md` \|
62	\| General "it's slow" with no specific signal \| Start with `references/hot-path-rules.md` \|
63
64	Multiple problem classes can overlap. Read the most relevant reference first,
65	then check the others if symptoms remain.
66
67	## Escalate Larger Fixes
68
69	If the likely fix is invasive, cross-cutting, or migration-heavy, stop and
70	present options before editing.
71
72	Examples:
73
74	- introducing digest or summary tables across multiple flows
75	- splitting documents to isolate frequently-updated fields
76	- reworking pagination or fetch strategy across several screens
77	- switching to a new index or denormalized field that needs migration-safe
78	rollout
79
80	When correctness depends on handling old and new states during a rollout,
81	consult the `convex-migration-helper` skill for the migration workflow.
82
83	## Workflow
84
85	### 1. Scope the problem
86
87	Pick one concrete user flow from the actual project. Look at the codebase,
88	client pages, and API surface to find the flow that matches the symptom.
89
90	Write down:
91
92	- entrypoint functions
93	- client callsites using `useQuery`, `usePaginatedQuery`, or `useMutation`
94	- tables read
95	- tables written
96	- whether the path is high-read, high-write, or both
97
98	### 2. Trace the full read and write set
99
100	For each function in the path:
101
102	1. Trace every `ctx.db.get()` and `ctx.db.query()`
103	2. Trace every `ctx.db.patch()`, `ctx.db.replace()`, and `ctx.db.insert()`
104	3. Note foreign-key lookups, JS-side filtering, and full-document reads
105	4. Identify all sibling functions touching the same tables
106	5. Identify reactive stats, aggregates, or widgets rendered on the same page
107
108	In Convex, every extra read increases transaction work, and every write can
109	invalidate reactive subscribers. Treat read amplification and invalidation
110	amplification as first-class problems.
111
112	### 3. Apply fixes from the relevant reference
113
114	Read the reference file matc

People who liked this also viewed

6 picks

Type

convex-performance-audit

89kinstalls8forks

View on GitHub

How to install convex-performance-audit?

get-convex/agent-skills/convex-performance-audit

$npx -y skills add get-convex/agent-skills --skill convex-performance-audit

Installs into the current project.

Summary

Audits Convex performance for reads, subscriptions, write contention, and function limits. Use for slow features, insights findings, OCC conflicts, or read amplification.

Files · 1

View on GitHub

SKILL.md

1	# Convex Performance Audit
2
3	Diagnose and fix performance problems in Convex applications, one problem class
4	at a time.
5
6	## When to Use
7
8	- A Convex page or feature feels slow or expensive
9	- `npx convex insights --details` reports high bytes read, documents read, or
10	OCC conflicts
11	- Low-freshness read paths are using reactivity where point-in-time reads would
12	do
13	- OCC conflict errors or excessive mutation retries
14	- High subscription count or slow UI updates
15	- Functions approaching execution or transaction limits
16	- The same performance pattern needs fixing across sibling functions
17
18	## When Not to Use
19
20	- Initial Convex setup, auth setup, or component extraction
21	- Pure schema migrations with no performance goal
22	- One-off micro-optimizations without a user-visible or deployment-visible
23	problem
24
25	## Guardrails
26
27	- Prefer simpler code when scale is small, traffic is modest, or the available
28	signals are weak
29	- Do not recommend digest tables, document splitting, fetch-strategy changes, or
30	migration-heavy rollouts unless there is a measured signal, a clearly
31	unbounded path, or a known hot read/write path
32	- In Convex, a simple scan on a small table is often acceptable. Do not invent
33	structural work just because a pattern is not ideal at large scale
34
35	## First Step: Gather Signals
36
37	Start with the strongest signal available:
38
39	1. If deployment Health insights are already available from the user or the
40	current context, treat them as a first-class source of performance signals.
41	2. If CLI insights are available, run `npx convex insights --details`. Use
42	`--prod`, `--preview-name`, or `--deployment-name` when needed.
43	- If the local repo's Convex CLI is too old to support `insights`, try
44	`npx -y convex@latest insights --details` before giving up.
45	3. If the repo already uses `convex-doctor`, you may treat its findings as
46	hints. Do not require it, and do not treat it as the source of truth.
47	4. If runtime signals are unavailable, audit from code anyway, but keep the
48	guardrails above in mind. Lack of insights is not proof of health, but it is
49	also not proof that a large refactor is warranted.
50
51	## Signal Routing
52
53	After gathering signals, identify the problem class and read the matching
54	reference file.
55
56	\| Signal \| Reference \|
57	\| -------------------------------------------------------------- \| ----------------------------------------- \|
58	\| High bytes or documents read, JS filtering, unnecessary joins \| `references/hot-path-rules.md` \|
59	\| OCC conflict errors, write contention, mutation retries \| `references/occ-conflicts.md` \|
60	\| High subscription count, slow UI updates, excessive re-renders \| `references/subscription-cost.md` \|
61	\| Function timeouts, transaction size errors, large payloads \| `references/function-budget.md` \|
62	\| General "it's slow" with no specific signal \| Start with `references/hot-path-rules.md` \|
63
64	Multiple problem classes can overlap. Read the most relevant reference first,
65	then check the others if symptoms remain.
66
67	## Escalate Larger Fixes
68
69	If the likely fix is invasive, cross-cutting, or migration-heavy, stop and
70	present options before editing.
71
72	Examples:
73
74	- introducing digest or summary tables across multiple flows
75	- splitting documents to isolate frequently-updated fields
76	- reworking pagination or fetch strategy across several screens
77	- switching to a new index or denormalized field that needs migration-safe
78	rollout
79
80	When correctness depends on handling old and new states during a rollout,
81	consult the `convex-migration-helper` skill for the migration workflow.
82
83	## Workflow
84
85	### 1. Scope the problem
86
87	Pick one concrete user flow from the actual project. Look at the codebase,
88	client pages, and API surface to find the flow that matches the symptom.
89
90	Write down:
91
92	- entrypoint functions
93	- client callsites using `useQuery`, `usePaginatedQuery`, or `useMutation`
94	- tables read
95	- tables written
96	- whether the path is high-read, high-write, or both
97
98	### 2. Trace the full read and write set
99
100	For each function in the path:
101
102	1. Trace every `ctx.db.get()` and `ctx.db.query()`
103	2. Trace every `ctx.db.patch()`, `ctx.db.replace()`, and `ctx.db.insert()`
104	3. Note foreign-key lookups, JS-side filtering, and full-document reads
105	4. Identify all sibling functions touching the same tables
106	5. Identify reactive stats, aggregates, or widgets rendered on the same page
107
108	In Convex, every extra read increases transaction work, and every write can
109	invalidate reactive subscribers. Treat read amplification and invalidation
110	amplification as first-class problems.
111
112	### 3. Apply fixes from the relevant reference
113
114	Read the reference file matc

People who liked this also viewed

6 picks

Type