convex-performance-audit

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

byget-convex· 29 skills

Installs

93k

Stars

Forks

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.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/get-convex/agent-skills" --skill "get-convex/agent-skills/convex-performance-audit"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/get-convex/agent-skills" that are relevant to the current task. Run `npx skills add "https://github.com/get-convex/agent-skills"` and select the relevant skills, then follow their instructions.

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 matching your problem class. Each reference includes
115	specific patterns, code examples, and a recommended fix order.
116
117	Do not stop at the single function named by an insight. Trace sibling readers
118	and writers touching the same tables.
119
120	### 4. Fix sibling functions together
121
122	When one function touching a table has a performance bug, audit sibling
123	functions for the same pattern.
124
125	After finding one problem, inspect both sibling readers and sibling writers for
126	the same table family, including companion digest or summary tables.
127
128	Examples:
129
130	- If one list query switches from full docs to a digest table, inspect the other
131	list queries for that table
132	- If one mutation isolates a frequently-updated field or splits a hot document,
133	inspect the other writers to the same table
134	- If one read path needs a migration-safe rollout for an unbackfilled field,
135	inspect sibling reads for the same rollout risk
136
137	Do not leave one path fixed and another path on the old pattern unless there is
138	a clear product reason.
139
140	### 5. Verify before finishing
141
142	Confirm all of these:
143
144	1. Results are the same as before, no dropped records
145	2. Eliminated reads or writes are no longer in the path where expected
146	3. Fallback behavior works when denormalized or indexed fields are missing
147	4. Frequently-updated fields are isolated from widely-read documents where
148	needed
149	5. Every relevant sibling reader and writer was inspected, not just the original
150	function
151
152	## Reference Files
153
154	- `references/hot-path-rules.md` - Read amplification, invalidation,
155	denormalization, indexes, digest tables
156	- `references/occ-conflicts.md` - Write contention, OCC resolution, hot document
157	splitting
158	- `references/subscription-cost.md` - Reactive query cost, subscription
159	granularity, point-in-time reads
160	- `references/function-budget.md` - Execution limits, transaction size, large
161	documents, payload size
162
163	Also check the official
164	[Convex Best Practices](https://docs.convex.dev/understanding/best-practices/)
165	page for additional patterns covering argument validation, access control, and
166	code organization that may surface during the audit.
167
168	## Checklist
169
170	- [ ] Gathered signals from insights, dashboard, or code audit
171	- [ ] Identified the problem class and read the matching reference
172	- [ ] Scoped one concrete user flow or function path
173	- [ ] Traced every read and write in that path
174	- [ ] Identified sibling functions touching the same tables
175	- [ ] Applied fixes from the reference, following the recommended fix order
176	- [ ] Fixed sibling functions consistently
177	- [ ] Verified behavior and confirmed no regressions

6 picks

Type

Run `npx skills use "https://github.com/get-convex/agent-skills" --skill "get-convex/agent-skills/convex-performance-audit"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/get-convex/agent-skills" that are relevant to the current task. Run `npx skills add "https://github.com/get-convex/agent-skills"` and select the relevant skills, then follow their instructions.

convex-performance-audit

How to install convex-performance-audit?

Related

convex-performance-audit

How to install convex-performance-audit?

Related