---
id: gh-convex-advisor
name: "convex-advisor"
url: https://skills.yangsir.net/skill/gh-convex-advisor
author: convex
domain: ai-system-observability-sre
tags: ["convex", "observability", "performance-optimization", "troubleshooting", "sre"]
install_count: 35300
rating: 4.60 (120 reviews)
github: https://github.com/convex/agent-skills/tree/main/skills/convex-advisor
---

# convex-advisor

> 读取 Convex 部署最近 72 小时的 insights 事件（读上限命中、读阈值逼近、OCC 写冲突、永久失败重试），再回到被标记函数的真实代码中定位根因，输出带原始证据的性能与成本发现及修复方案。适合上线前体检与线上读放大、写热点、费用超支的快速排查，让结论基于运行时事实而非经验猜测。

**Stats**: 35,300 installs · 4.6/5 (120 reviews)

## Before / After 对比

### 性能根因定位时长

**Before**:

线上出现读放大与写冲突告警时，开发者只能翻日志、逐表猜测问题出在哪，再凭经验改索引，一次排查往往耗费数小时，成本异常也难以被及时量化。

**After**:

此技能直接读取部署 72 小时的真实 insights 事件，逐条回到被标记函数的代码定位根因，并附上原始证据与具体修复方案，排查从数小时压缩到十几分钟，成本风险在放量前即被量化。

| Metric | Before | After | Change |
|---|---|---|---|
| 根因定位耗时 | 180分钟 | 15分钟 | -92% |
| 需人工翻阅的日志条目 | 200条 | 5条 | -98% |

### 无索引读放大问题发现率

**Before**:

缺失索引导致的全表扫描与计数型读取长期潜伏，只有在账单超支或用户抱怨变慢时才被发现，团队缺少可复现的定位依据。

**After**:

该 Skill 把 72 小时窗口内每一次读上限命中与阈值逼近都转成 confirmed 级别的发现，标明函数、表名与读取字节数，团队可在影响扩大前完成索引加固与分页改造。

| Metric | Before | After | Change |
|---|---|---|---|
| 读放大问题提前发现率 | 25% | 90% | +260% |
| 每月因读放大多出的云成本占比 | 30% | 6% | -80% |

## Readme

<!-- GENERATED from convex-agents content/capabilities/convex-advisor.json — do not edit by hand. -->

# 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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.


---
*Source: https://skills.yangsir.net/skill/gh-convex-advisor*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-convex-advisor/markdown*