Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

insforge-debug

Use when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx/5xx, gateway timeout 502/503/504, edge function failure or timeout, login/OAuth/auth errors, RLS denial, realtime channel issues, slow query on one endpoint, edge function or Vercel deploy failure), proactive audits (security/RLS review, performance/index review, system health check, pre-launch readiness), or when the user has an error but doesn't know where to start.

InsForge · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add InsForge/insforge-skills --skill insforge-debug

About this skill


name: insforge-debug description: >- Use when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx/5xx, gateway timeout 502/503/504, edge function failure or timeout, login/OAuth/auth errors, RLS denial, realtime channel issues, slow query on one endpoint, edge function or Vercel deploy failure), proactive audits (security/RLS review, performance/index review, system health check, pre-launch readiness), or when the user has an error but doesn't know where to start. license: Apache-2.0

InsForge Debug

Diagnose problems in InsForge projects by combining the backend's observability primitives — logs, metrics, db-health, advisor, policies, metadata, error objects, deploy state, and AI assist. This skill provides:

  1. A reference per debug primitive (one observability surface each — under references/)
  2. Symptom Recipes (below) that name the primitive sequence for known reactive symptoms and proactive audits

Always use npx -y @insforge/cli — never install the CLI globally.

Fastest Path: AI-Assisted Triage

When the user gives a concrete description (error message, failing URL, HTTP status), hand it to the InsForge debug agent. Unlike the other primitives, this one returns suggestions, not just observations — verify the diagnosis against the primitives it cites before acting on it.

npx -y @insforge/cli diagnose --ai "<issue description>"

See references/ai-assisted.md for when to use this first vs when to skip, and how to verify the output.

Debug Primitives

Each primitive is one independently-queryable observability surface backed by a distinct underlying data source. Real diagnoses are compositions of primitives.

All commands run via npx -y @insforge/cli .... The (command) shown next to each primitive is the actual CLI command — primitive names are concept labels, not CLI subcommand names (e.g., "DB health" is diagnose db, not diagnose db-health; "Policies" is db policies, not diagnose policies).

Primitive (command)What you seeReference
Logs (logs <source>; diagnose logs for cross-source aggregate)Time-stream of events from 5 backend sources (insforge.logs / postgREST.logs / postgres.logs / function.logs / function-deploy.logs)references/logs.md
Metrics (diagnose metrics)EC2 instance time-series (CPU / memory / disk / network) over 1h / 6h / 24h / 7dreferences/metrics.md
DB health (diagnose db)Current Postgres state via 7 named checks (connections / slow-queries / bloat / size / index-usage / locks / cache-hit)references/db-health.md
Advisor (diagnose advisor --json)Static-scan issues across 3 categories (security / performance / health) with ruleId / affectedObject / recommendationreferences/advisor.md
Policies (db policies)Active RLS rules from pg_policies (USING / WITH CHECK per cmd per role) — returns all policies as a dumpreferences/policies.md
Metadata (metadata --json)Declarative backend state dump (auth config / tables / buckets / functions / AI models / realtime channels)references/metadata.md
Error objects (no command — read SDK / HTTP response)SDK error envelope + HTTP status — the routing table from a client-visible error to the right log sourcereferences/error-objects.md
Deploy state (deployments list + deployments status <id> --json + logs function-deploy.logs)Frontend (Vercel) deployment history + per-deploy metadata, plus edge function deploy logsreferences/deploy-state.md
AI assist (diagnose --ai "<description>")LLM agent that combines the other primitives — returns a diagnosis with suggestionsreferences/ai-assisted.md

Symptom Recipes

Each recipe is a primitive call sequence with one-line "look for X" at each step. Command syntax, flags, and deep interpretation are in the per-primitive references above.

Recipe: SDK returned { data: null, error: { code, message } }

  1. error-objects — read code/message/details. If code starts with PGRST*, route by prefix using the table in the reference.
  2. logs (matching source per error-objects routing) — find the error timestamp, get the full backend-side context.
  3. db-health (connections, locks, slow-queries) — only if the error suggests DB issue (PostgREST timeout, lock conflict).

Recipe: HTTP 4xx/5xx response on a specific request

  1. error-objects — use the HTTP status routing table to pick the log source (each status has a distinct path; 429 is special).
  2. logs (right source for that status) — find the failing request line and error.
  3. metrics — only for 5xx patterns spanning multiple endpoints, to confirm system-wide load issue.

Recipe: RLS access issue (403 on write, or empty result on read)

Same bug, two surfacings. Writes (INSERT / UPDATE / DELETE) fail loudly with 403. Reads (SELECT) fail silently with an empty array — PostgREST filters denied rows out instead of returning 403, so the request looks successful with zero rows. Diagnosis path is the same except step 1 only applies to the 403 variant.

  1. logs (postgREST.logs) — 403 variant only: find the policy violation event with table and role context. Empty-result variant: skip — no error is logged for silently-filtered rows.
  2. policies — list policies for that table; walk USING / WITH CHECK against the actual request and the JWT claim used.
  3. metadata — verify auth config (which claim feeds auth.uid() / requesting_user_id(); for third-party auth like Clerk/
Read the complete source ↗