Convex Doctor

Convex Doctor Skill

Run through these checks when writing or reviewing Convex backend and client code. Based on the convex-doctor CLI which scores projects 0-100 across 72 rules in 7 categories.

How to use this skill

1. Before shipping backend changes, scan the affected files against the rules below.
2. Flag violations by severity: error (must fix), warning (should fix), info (consider fixing).
3. Suggest the fix inline when flagging.
4. If the user has convex-doctor installed, recommend running npx convex-doctor -v for a full report.

Security (13 rules, 1.5x weight)

Performance (13 rules, 1.2x weight)

Correctness (20 rules, 1.5x weight)

Schema (9 rules, 1.0x weight)

Architecture (8 rules, 0.8x weight)

Configuration (5 rules, 1.0x weight)

Client-Side (4 rules, 1.0x weight)

Scoring

Health score is 0-100. Each finding deducts points based on severity and category weight, with per-rule caps.

Common fix patterns

Replace .filter() with .withIndex()

// Bad
const docs = await ctx.db.query("tasks").filter((q) => q.eq(q.field("userId"), userId)).collect();

// Good (add index "by_userId" on ["userId"] in schema)
const docs = await ctx.db.query("tasks").withIndex("by_userId", (q) => q.eq("userId", userId)).collect();

Replace loop mutations with batch

// Bad
for (const id of ids) {
  await ctx.runMutation(internal.tasks.complete, { taskId: id });
}

// Good: single mutation that handles the batch
const updates = ids.map((id) => ctx.db.patch(id, { completed: true }));
await Promise.all(updates);

Fix Date.now() in queries

// Bad (in a query)
const cutoff = Date.now() - 86400000;

// Good: pass timestamp as an argument from the caller
args: { cutoff: v.number() },

Fix unbounded collect

// Bad
const all = await ctx.db.query("messages").collect();

// Good: paginate or limit
const recent = await ctx.db.query("messages").order("desc").take(50);

CLI reference

npx convex-doctor        # basic scan
npx convex-doctor -v     # verbose with file paths and line numbers
npx convex-doctor --format json  # JSON output for CI
npx convex-doctor --score        # score only (prints a number)
npx convex-doctor --diff main    # only files changed vs base branch

Source: https://github.com/nooesc/convex-doctor