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-debugAbout 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:
- A reference per debug primitive (one observability surface each — under
references/) - 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 see | Reference |
|---|---|---|
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 / 7d | references/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 / recommendation | references/advisor.md |
Policies (db policies) | Active RLS rules from pg_policies (USING / WITH CHECK per cmd per role) — returns all policies as a dump | references/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 source | references/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 logs | references/deploy-state.md |
AI assist (diagnose --ai "<description>") | LLM agent that combines the other primitives — returns a diagnosis with suggestions | references/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 } }
- error-objects — read code/message/details. If code starts with
PGRST*, route by prefix using the table in the reference. - logs (matching source per error-objects routing) — find the error timestamp, get the full backend-side context.
- 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
- error-objects — use the HTTP status routing table to pick the log source (each status has a distinct path; 429 is special).
- logs (right source for that status) — find the failing request line and error.
- 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.
- 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. - policies — list policies for that table; walk USING / WITH CHECK against the actual request and the JWT claim used.
- metadata — verify auth config (which claim feeds
auth.uid()/requesting_user_id(); for third-party auth like Clerk/