Live-deployment advisor

Static review guesses; the deployment KNOWS. The official Convex MCP ships an

insights

tool with typed 72h health events per function — documentsReadLimit / bytesReadLimit (hard limit hits), documentsReadThreshold / bytesReadThreshold (approaching), occFailedPermanently / occRetried (write contention) — each carrying evidence (table_name, bytes_read, documents_read, occ document id + retry count). The advisor turns each event into a root-caused finding by reading the flagged function's actual code, and emits findings on the findings bus (specs/finding.schema.json) so fixers can be dispatched and launch-readiness can score.

Workflow

GUARD: run deploy-guard step 0-1 — identify + announce the deployment being read. Reading insights/logs on prod is allowed read-only; never enable mutating prod access for an advisory pass.
GATHER (deterministic, via the official Convex MCP):
```
status
```
→ deployment selector;
```
insights
```
→ the typed 72h events;
```
tables
```
→ schema + row counts;
```
functionSpec
```
→ the public/internal surface. The
```
insights
```
tool is only available on cloud dev/prod deployments when logged in as a user (not on previews or deploy-key-scoped contexts) and needs ~72h of traffic; if it returns nothing or is unavailable, say so and fall back to offering convex-reviewer — do NOT invent findings.
ROOT-CAUSE each insight event by reading the flagged function's code:
- bytesReadThreshold/Limit or documentsReadThreshold/Limit → look for
```
.collect()
```
  / unindexed
```
.filter()
```
  / missing pagination on the named table; the fix is an index +
```
.withIndex
```
  ,
```
.take(n)
```
  , or
```
.paginate
```
  (convex-expert patterns), or an aggregate component for counting shapes.
- occRetried / occFailedPermanently → look for read-modify-write hotspots on the named document (shared counters, status toggles); the fix is @convex-dev/sharded-counter, narrowing the read set, or moving contention to a workpool.
- repeated failures in
```
logs
```
  (status: failure) → classify: crash loop in a cron, validator rejections, unhandled error shapes.
EMIT findings per specs/finding.schema.json: class perf/correctness/cost, severity from the insight kind (limit hits = high, thresholds = med, retried = med, permanent OCC failure = high), locus {kind: deployment, functionId, tableName}, evidence {kind: insight-event, detail: the raw event}, confidence: confirmed (the event happened — it is not a hypothesis), fixCapability + autofixable where the repair is mechanical.
REPORT: findings ranked by severity, each with (a) the runtime evidence in one line ('messages:list read 4.2MB from messages 31× yesterday'), (b) the code-level root cause with file:line, (c) the concrete fix and which capability applies it. Offer to apply fixes; apply only on confirmation, then re-run
```
insights
```
after traffic to verify the trend, or re-run the static check immediately.
Scope discipline: this is a health/perf/cost pass. Route authz findings to convex-authz, code-idiom findings to convex-reviewer, error triage to sentinel — emit a pointer finding rather than duplicating their work.

Rules

Evidence-not-vibes: every finding cites a real insight event, log line, or table stat — if the deployment has no evidence, the advisor has no findings (offer convex-reviewer instead).
Read-only by construction: an advisory pass never mutates any deployment and never enables prod mutation flags (deploy-guard discipline applies).
Root-cause in the code before reporting: an insight event names the symptom; the finding must name the line and the mechanism.
Emit on the findings bus (specs/finding.schema.json), confidence: confirmed — runtime events are facts, not hypotheses.
Severity from the event kind: limit-hit / permanent-OCC-failure = high; threshold / retried = med.
Stay in lane: perf/cost/health only — hand authz to convex-authz, style to convex-reviewer, error triage to sentinel.
Prefer component fixes over hand-rolls when they match (sharded-counter for OCC on counters, aggregate for count scans) — same bias as suggest.

convex-advisor

NPX Install

Tags

SKILL.md Content

Live-deployment advisor

Workflow

Rules