InsForge/insforge-skills

InsForge Debug

Diagnostique problemas en proyectos InsForge combinando las primitivas de observabilidad del backend — logs, métricas, salud de base de datos, asesor, políticas, metadatos, objetos de error, estado de deploy y asistencia de IA. Esta habilidad proporciona:

1. Una referencia por primitiva de depuración (una superficie de observabilidad cada una — en references/)
2. Recetas de Síntomas (a continuación) que nombran la secuencia de primitivas para síntomas reactivos conocidos y auditorías proactivas

Utilice siempre npx -y @insforge/cli — nunca instale la CLI globalmente.

Camino Más Rápido: Triaje Asistido por IA

Cuando el usuario proporciona una descripción concreta (mensaje de error, URL que falla, estado HTTP), entréguela al agente de depuración de InsForge. A diferencia de otras primitivas, esta devuelve sugerencias, no solo observaciones — verifique el diagnóstico contra las primitivas que cita antes de actuar.

npx -y @insforge/cli diagnose --ai "<descripción del problema>"

Consulte references/ai-assisted.md para saber cuándo usar esto primero, cuándo omitirlo y cómo verificar el resultado.

Primitivas de Depuración

Cada primitiva es una superficie de observabilidad consultable de forma independiente respaldada por una fuente de datos subyacente distinta. Los diagnósticos reales son composiciones de primitivas.

Todos los comandos se ejecutan mediante npx -y @insforge/cli .... El (comando) que se muestra junto a cada primitiva es el comando real de la CLI — los nombres de las primitivas son etiquetas de concepto, no subcomandos de la CLI (por ejemplo, "Salud de BD" es diagnose db, no diagnose db-health; "Políticas" es db policies, no diagnose policies).

Primitiva (comando)	Qué se ve	Referencia
Logs (logs <source>; diagnose logs para agregado entre fuentes)	Flujo temporal de eventos de 5 fuentes del backend (insforge.logs / postgREST.logs / postgres.logs / function.logs / function-deploy.logs)	references/logs.md
Métricas (diagnose metrics)	Series temporales de instancia EC2 (CPU / memoria / disco / red) en 1h / 6h / 24h / 7d	references/metrics.md
Salud de BD (diagnose db)	Estado actual de Postgres mediante 7 verificaciones con nombre (connections / slow-queries / bloat / size / index-usage / locks / cache-hit)	references/db-health.md
Asesor (diagnose advisor --json)	Problemas de escaneo estático en 3 categorías (security / performance / health) con ruleId / affectedObject / recommendation	references/advisor.md
Políticas (db policies)	Reglas RLS activas de pg_policies (USING / WITH CHECK por comando por rol) — devuelve todas las políticas como un volcado	references/policies.md
Metadatos (metadata --json)	Volcado de estado declarativo del backend (configuración de autenticación / tablas / buckets / funciones / modelos de IA / canales en tiempo real)	references/metadata.md
Objetos de error (sin comando — leer SDK / respuesta HTTP)	Envoltorio de error del SDK + estado HTTP — la tabla de enrutamiento desde un error visible para el cliente hasta la fuente de registro correcta	references/error-objects.md
Estado de deploy (deployments list + deployments status <id> --json + logs function-deploy.logs)	Historial de implementaciones del frontend (Vercel) + metadatos por implementación, más logs de deploy de funciones edge	references/deploy-state.md
Asistencia IA (diagnose --ai "<description>")	Agente LLM que combina las otras primitivas — devuelve un diagnóstico con sugerencias	references/ai-assisted.md

Recetas de Síntomas

Cada receta es una secuencia de llamadas a primitivas con una línea "buscar X" en cada paso. La sintaxis de comandos, las banderas y la interpretación detallada están en las referencias por primitiva anteriores.

Receta: El SDK devolvió { data: null, error: { code, message } }

1. objetos de error — leer código/mensaje/detalles. Si el código comienza con PGRST*, enrutar por prefijo usando la tabla en la referencia.
2. logs (fuente coincidente según enrutamiento de objetos de error) — encontrar la marca de tiempo del error, obtener el contexto completo del lado del backend.
3. salud de BD (connections, locks, slow-queries) — solo si el error sugiere un problema de BD (timeout de PostgREST, conflicto de bloqueo).

Receta: Respuesta HTTP 4xx/5xx en una solicitud específica

1. objetos de error — usar la tabla de enrutamiento de estado HTTP para elegir la fuente de registro (cada estado tiene una ruta distinta; 429 es especial).
2. logs (fuente correcta para ese estado) — encontrar la línea de solicitud fallida y el error.
3. métricas — solo para patrones 5xx que abarcan múltiples endpoints, para confirmar un problema de carga a nivel de sistema.

Receta: Problema de acceso RLS (403 en escritura, o resultado vacío en lectura)

Mismo error, dos presentaciones. Las escrituras (INSERT / UPDATE / DELETE) fallan ruidosamente con 403. Las lecturas (SELECT) fallan silenciosamente con un array vacío — PostgREST filtra las filas denegadas en lugar de devolver 403, por lo que la solicitud parece exitosa con cero filas. La ruta de diagnóstico es la misma, excepto que el paso 1 solo se aplica a la variante 403.

1. logs (postgREST.logs) — solo variante 403: encontrar el evento de violación de política con contexto de tabla y rol. Variante de resultado vacío: omitir — no se registra ningún error para filas filtradas silenciosamente.
2. políticas — listar políticas para esa tabla; revisar USING / WITH CHECK contra la solicitud real y el reclamo JWT utilizado.
3. metadatos — verificar la configuración de autenticación (qué reclamo alimenta auth.uid() / requesting_user_id(); para autenticación de terceros como Clerk/Auth0, ¿está el proveedor registrado como un emisor JWT?).
4. consulta a BD (db query "<sql>") — solo variante de resultado vacío: confirmar que las filas que deberían ser visibles realmente existen consultando como rol de servicio (no como el usuario): npx -y @insforge/cli db query "SELECT id, user_id FROM <table>". Distingue entre "RLS filtró todo" y "no existen datos coincidentes".

Receta: Fallo de inicio de sesión / errores de callback OAuth / token expirado

1. logs (insforge.logs) — encontrar errores de autenticación con marca de tiempo y contexto del proveedor.
2. metadatos — verificar que el proveedor esté habilitado, las URL de redireccionamiento coincidan exactamente con la URL de callback (protocolo + host + ruta).

Receta: Error de tiempo de ejecución / timeout de función edge

1. logs (function.logs) — obtener la pila de errores y el contexto de ejecución.
2. metadatos — confirmar que la función existe y tiene status: "active".
3. (Si es necesario) npx -y @insforge/cli functions code <slug> — inspeccionar el código fuente en busca de problemas evidentes.

Receta: functions deploy falló

1. estado de deploy (function-deploy.logs) — encontrar el error de compilación/inserción.
2. metadatos — confirmar si la función terminó en la lista activa (detección de implementación parcial).

Receta: deployments deploy falló (Vercel)

1. estado de deploy (deployments list + status <id> --json) — leer status, metadata.webhookEventType y envVarKeys.
2. Local npm run build — reproducir el mismo error localmente para una iteración más rápida.

Receta: Una consulta lenta / un endpoint lento

1. logs (postgres.logs) — encontrar el texto de la consulta y la marca de tiempo.
2. salud de BD (slow-queries, index-usage) — slow-queries solo lo detecta mientras aún se está ejecutando (>5s snapshot); verificar index-usage en busca de un índice faltante. ¿Ya terminó? asesor (--category performance --json) tiene el texto de pg_stat_statements + tiempo medio; el paso 1 tiene la marca de tiempo.
3. políticas — si es una tabla con protección RLS, verificar que la política no esté agregando uniones ocultas.

Receta: "La memoria está al ~80% pero nada es lento"

1. Es esperado — dígalo primero. Una instancia dedicada de Postgres convierte la RAM inactiva en búfers compartidos y caché de páginas; la memoria alta constante con poco tráfico es su estado saludable, no una fuga (references/metrics.md, "Memoria: alta es normal").
2. métricas (--range 24h) — solo una tendencia creciente o muertes/reinicios por OOM cambian la respuesta. La evidencia de OOM está en postgres.logs como las secuelas de la recuperación tras un fallo ("terminating connection because of crash of another server process" / "automatic recovery in progress").
3. Con evidencia de OOM, la solución es espacio libre: actualizar a un plan de pago y elegir un tamaño de instancia mayor (panel de control → Configuración del proyecto → Cómputo y Disco). El OOM en las instancias más pequeñas bajo carga real es común y esperado — nunca "reiniciar para liberar memoria".

Receta: Todas las respuestas lentas / CPU/memoria altos (incidente activo)

1. métricas (--range 1h) — confirmar presión a nivel de sistema (CPU / memoria / disco).
2. salud de BD — la BD es el cuello de botella más común; verificar connections, locks, slow-queries.
3. logs (diagnose logs agregado) — patrones de error en todas las fuentes en la marca de tiempo del pico.
4. asesor (--severity critical) — problemas conocidos preexistentes que pueden explicar la degradación.

Receta: El canal en tiempo real no se conecta / mensajes faltantes

1. logs (insforge.logs) — errores de WebSocket y fallos de suscripción.
2. metadatos — verificar que el patrón del canal coincida con lo que el cliente suscribe, enabled: true.
3. políticas — RLS en la tabla subyacente (el tiempo real entrega cambios de fila; RLS controla qué filas ve el suscriptor).

Receta: Límite de tasa 429

1. objetos de error — confirmar estado 429. No se registran logs para 429; no se devuelve ninguna cabecera Retry-After. No pierda tiempo buscando en logs.
2. métricas (--range 1h) — contexto de carga general del backend.
3. La solución siempre es del lado del cliente: debounce, lotes, backoff exponencial, eliminar bucles de reintento.

Receta: Timeout de puerta de enlace (502 / 503 / 504) en una URL específica

Enrute por subsistema de URL antes de profundizar:

Patrón de URL	Profundizar en
/api/database/records/...	logs (postgREST.logs → postgres.logs) + salud de BD (locks, slow-queries)
/functions/<slug>	logs (function.logs) — la función puede estar en bucle de fallo
/api/auth/...	logs (insforge.logs)
Cualquier ruta durante un pico a nivel de sistema	métricas (--range 1h)

504s en rutas no relacionadas en una instancia pequeña: sospechar OOM primero. Los timeouts de puerta de enlace intermitentes que afectan a la base de datos, la autenticación y las funciones por igual son la firma clásica de falta de memoria en los tamaños de instancia más pequeños: el kernel mata a Postgres, cada solicitud en curso agota el tiempo de espera en la puerta de enlace mientras se ejecuta la recuperación tras un fallo, y se repite en el siguiente pico de carga.

Ruta rápida: npx -y @insforge/cli diagnose incident (requiere inicio de sesión en la plataforma). El informe se construye completamente en el lado de la nube — historial de scraping de Prometheus, registros de la plataforma, un sondeo de base de datos saliente — por lo que funciona incluso mientras la instancia está caída o atascada, justo cuando diagnose logs deja de responder. Devuelve un veredicto (oom_likely, platform_operation_in_progress, paused_or_suspended, metrics_stopped, down_unknown, no_incident_detected) con la evidencia y la acción recomendada; oom_likely ya significa que las comprobaciones de correlación de reinicio/memoria a continuación pasaron en el lado de la plataforma.

Si el comando no está disponible (CLI/backend antiguo, modo de enlace --api-key), confirmar manualmente en logs (postgres.logs) mediante las secuelas de la recuperación tras un fallo — "terminating connection because of crash of another server process" / "automatic recovery in progress" — correlacionado temporalmente con la ráfaga 5xx: la evidencia de recuperación por sí sola solo prueba un reinicio no limpio de Postgres, por lo que las marcas de tiempo deben coincidir antes de que OOM se convierta en el diagnóstico principal (references/metrics.md). Con esa evidencia, la solución es espacio libre, no un bucle de reintento:

1. Actualizar la instancia — npx -y @insforge/cli projects upgrade-instance <type> (nano → micro → small → medium → large → xl), o panel de control → Configuración del proyecto → Cómputo y Disco. En el plan gratuito, actualice primero a un plan de pago, luego elija el tamaño. El cambio de tamaño cambia la factura y la CLI solicita confirmación interactiva — obtenga primero la aprobación del usuario, luego ejecute sin supervisión con el indicador --yes a nivel de CLI (el -y en npx -y es el indicador de instalación de npm, no el de omitir confirmación). El cambio de tamaño es asíncrono — sondee projects get hasta que operation_status se despeje antes de declarar el incidente resuelto.
2. El cambio de tamaño reinicia el proyecto como parte del cambio, lo que también limpia cualquier estado atascado — no hay un reinicio separado dirigido al usuario, y un reinicio simple solo compraría minutos antes de que el siguiente pico vuelva a causar OOM. El OOM bajo carga real en los tamaños más pequeños es común y esperado, no un error.

Receta: Auditoría previa al lanzamiento / proactiva

Requiere inicio de sesión en la plataforma (npx -y @insforge/cli login). No disponible cuando el proyecto está vinculado mediante --api-key — recurra a salud de BD + políticas + metadatos para una auditoría manual en ese caso.

1. asesor — escaneo completo, luego --severity critical primero, luego advertencias.
2. asesor (--category security) — centrarse en problemas de seguridad; verificar de forma cruzada con políticas (cobertura RLS) y metadatos (configuración de autenticación, buckets públicos, presencia de secretos).
3. asesor (--category performance) — verificar de forma cruzada con salud de BD (slow-queries, index-usage, bloat).
4. asesor (--category health) — verificar de forma cruzada con métricas (tendencias de recursos en 7d).
5. Después de las correcciones, volver a ejecutar asesor y confirmar isResolved: true para cada ruleId abordado.

Receta: No sé por dónde empezar

1. asistencia IA (diagnose --ai "<error o URL>") — obtener una hipótesis inicial.
2. Verificar volviendo a revisar las primitivas que nombra el diagnóstico. Confíe en las observaciones de las primitivas por encima de la sugerencia.

Cuando la Causa Raíz es el Propio InsForge

Algunos diagnósticos terminan en un defecto del lado de InsForge, no en una configuración incorrecta del proyecto: un error o regresión de la plataforma, una llamada al SDK que se comporta mal, documentación o una habilidad que contradice el comportamiento observado, o una capacidad faltante. Una sesión de depuración es exactamente donde estos se confirman — repórtelos mientras la evidencia está a mano:

npx -y @insforge/cli feedback --json \
  --type bug --component backend --area db \
  --title "<resumen de una línea>" \
  --detail "<lo que ocurrió vs lo esperado, reproducción mínima>" \
  --command "<la llamada fallida>" \
  --error "<error textual de los logs>" \

…

[truncado para traducción]