# Convex Advisor

> Lee los insights de 72h del deployment de Convex (límites de lectura, contención OCC), root-causea cada evento en el código y reporta hallazgos de performance/costo con evidencia y fixes.

Fuente: https://skillsagentes.com/skills/get-convex/agent-skills/convex-advisor
Markdown: https://skillsagentes.com/skills/get-convex/agent-skills/convex-advisor.md

Repositorio: https://github.com/get-convex/agent-skills
Autor: get-convex
Licencia: Apache-2.0
Actualizado: el mes pasado
Coste de contexto: 39 tok instalada, 1.1k tok al activarse, 1.1k tok con todos los archivos del bundle
Bundle: 1 archivo, 4 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add get-convex/agent-skills --skill convex-advisor --agent claude-code
# Cursor
npx -y skills add get-convex/agent-skills --skill convex-advisor --agent cursor
# Codex
npx -y skills add get-convex/agent-skills --skill convex-advisor --agent codex
# Gemini CLI
npx -y skills add get-convex/agent-skills --skill convex-advisor --agent gemini
# Windsurf
npx -y skills add get-convex/agent-skills --skill convex-advisor --agent windsurf
# Cline
npx -y skills add get-convex/agent-skills --skill convex-advisor --agent cline
```

## Qué hace

- Lee los eventos de salud de 72h del deployment de Convex vía la herramienta insights del MCP oficial (límites de lectura, contención OCC)
- Root-causea cada evento leyendo el código real de la función marcada
- Emite findings evidenciados en el bus specs/finding.schema.json con severidad, locus y evidencia
- Reporta hallazgos ordenados por severidad con evidencia en runtime, causa raíz con file:line y el fix concreto
- Ofrece aplicar los fixes solo tras confirmación, sin mutar nunca el deployment

## Cuándo usarla

- Quieres saber qué funciones están golpeando límites de lectura o sufriendo contención OCC en producción
- Necesitas evidencia real de 72h de tráfico en vez de una revisión estática de código
- Quieres priorizar findings de performance/costo por severidad con causa raíz en el código

## Cuándo no

- El insights tool no está disponible (previews o contextos con deploy-key) o no hay ~72h de tráfico: usa convex-reviewer en su lugar
- El hallazgo es de autorización (usa convex-authz), estilo/idioma de código (convex-reviewer) o triage de errores (sentinel)

## Qué la activa

- "Revisa los insights de 72h de mi deployment de Convex y dime qué funciones tienen problemas"
- "¿Por qué esta función está fallando por contención OCC en producción?"
- "Analiza el consumo de lecturas de mis funciones de Convex y sugiere índices o paginación"

## Antes de instalar

- Requiere el MCP oficial de Convex con la herramienta insights, disponible solo en deployments cloud dev/prod logueados como usuario (no en previews ni contextos con deploy-key) y con ~72h de tráfico acumulado.

## Archivos

- SKILL.md — 4 KB

## SKILL.md

Reproducido tal cual desde get-convex/agent-skills bajo Apache-2.0. Esta sección es el documento original y está en inglés.

<!-- 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.

## Dónde encaja

- Categoría: [Bases de datos](https://skillsagentes.com/categorias/bases-de-datos.md) — Diseño de esquemas, migraciones y optimización de consultas.
- Creador: [get-convex](https://skillsagentes.com/creators/get-convex.md) — 33 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Convex Quickstart](https://skillsagentes.com/skills/get-convex/agent-skills/convex-quickstart.md): Levanta un template Next.js + Convex barebones a partir de una idea en una frase.
- [Convex Authz](https://skillsagentes.com/skills/get-convex/agent-skills/convex-authz.md): Audita y refuerza la autorización de una app Convex: impersonación por identity-from-arg, checks de ownership por documento faltantes, queries públicas que filtran datos por un id del cliente y escrituras en un contenedor ajeno.
- [Convex Design](https://skillsagentes.com/skills/get-convex/agent-skills/convex-design.md): Diseña y construye backends reactivos y type-safe de nivel producción en Convex: schema, queries/mutations/actions, índices, auth, storage, scheduling, multiplayer en tiempo real y workflows LLM/agentes.
- [Convex Expert](https://skillsagentes.com/skills/get-convex/agent-skills/convex-expert.md): Especialista en el backend de Convex: código dentro de convex/ (funciones, schemas, índices, queries, mutations, actions, endpoints HTTP, cron jobs, storage, auth y componentes).
- [Convex Agent](https://skillsagentes.com/skills/get-convex/agent-skills/convex-agent.md): Añade un backend de agente de IA / RAG (@convex-dev/agent) a la app Convex.

## Skills relacionadas

- [Lamindb](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/lamindb.md): Úsalo con LaminDB, el lakehouse de código abierto nativo en linaje para datasets y modelos biológicos: configuración, registro de artefactos, búsqueda, trazabilidad, validación, anotación con ontologías (Bionty) y almacenamiento.
- [Vector Index Tuning](https://skillsagentes.com/skills/wshobson/agents/vector-index-tuning.md): Optimiza el rendimiento de índices vectoriales en latencia, recall y memoria; útil al ajustar parámetros HNSW, elegir cuantización o escalar infraestructura de búsqueda vectorial.
- [Projection Patterns](https://skillsagentes.com/skills/wshobson/agents/projection-patterns.md): Construye modelos de lectura y proyecciones a partir de flujos de eventos; útil para CQRS, vistas materializadas y optimización de consultas en sistemas event-sourced.
- [Event Store Design](https://skillsagentes.com/skills/wshobson/agents/event-store-design.md): Diseña e implementa event stores para sistemas de event sourcing: infraestructura, elección de tecnología y patrones de persistencia de eventos.
- [Database Migration](https://skillsagentes.com/skills/wshobson/agents/database-migration.md): Ejecuta migraciones de bases de datos entre ORMs y plataformas con estrategias zero-downtime, transformación de datos y procedimientos de rollback.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)