From insforge
Diagnoses problems in InsForge projects using logs, metrics, DB health, and other observability primitives. Covers reactive failures and proactive audits.
How this skill is triggered — by the user, by Claude, or both
Slash command
/insforge:insforge-debugThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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:
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:
references/)Always use npx @insforge/cli — never install the CLI globally.
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 @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.
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 @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 |
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.
{ data: null, error: { code, message } }PGRST*, route by prefix using the table in the reference.connections, locks, slow-queries) — only if the error suggests DB issue (PostgREST timeout, lock conflict).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.
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.auth.uid() / requesting_user_id(); for third-party auth like Clerk/Auth0, is the provider registered as a JWT issuer?).db query "<sql>") — empty-result variant only: confirm rows that should be visible actually exist by querying as service role (not as the user): npx @insforge/cli db query "SELECT id, user_id FROM <table>". Distinguishes "RLS filtered everything" from "no matching data exists".insforge.logs) — find auth errors with timestamp and provider context.function.logs) — get the error stack and execution context.status: "active".npx @insforge/cli functions code <slug> — inspect the source for obvious issues.functions deploy failedfunction-deploy.logs) — find the build/push error.deployments deploy failed (Vercel)deployments list + status <id> --json) — read status, metadata.webhookEventType, and envVarKeys.npm run build — reproduce the same error locally for faster iteration.postgres.logs) — find the query text and timestamp.slow-queries, index-usage) — confirm it's in pg_stat_statements; check for missing index.--range 1h) — confirm system-wide pressure (CPU / memory / disk).connections, locks, slow-queries.diagnose logs aggregate) — error patterns across sources at the spike timestamp.--severity critical) — pre-existing known issues that may explain the degradation.insforge.logs) — WebSocket errors and subscription failures.enabled: true.Retry-After header is returned. Don't waste time grepping logs.--range 1h) — overall backend load context.Route by URL subsystem before drilling:
| URL pattern | Drill into |
|---|---|
/api/database/records/... | logs (postgREST.logs → postgres.logs) + db-health (locks, slow-queries) |
/functions/<slug> | logs (function.logs) — function may be crash-looping |
/api/auth/... | logs (insforge.logs) |
| Any path during system-wide spike | metrics (--range 1h) |
Requires Platform login (
npx @insforge/cli login). Not available when the project is linked via--api-key— fall back todb-health+policies+metadatafor a manual audit in that case.
--severity critical first, then warnings.--category security) — focus on security issues; cross-verify with policies (RLS coverage) and metadata (auth config, public buckets, secret presence).--category performance) — cross-verify with db-health (slow-queries, index-usage, bloat).--category health) — cross-verify with metrics (resource trends over 7d).isResolved: true for each addressed ruleId.diagnose --ai "<error or URL>") — get a starting hypothesis.npx claudepluginhub insforge/insforge --plugin insforgeManages InsForge backend and cloud infrastructure via CLI: projects, SQL, migrations, RLS policies, functions, storage, deployments, compute, secrets, config, schedules, logs, diagnostics, import/export, AI/OpenRouter setup, Stripe/Razorpay payments, and backend branches.
Sets up Supabase observability with dashboard reports, CLI inspect commands for Postgres diagnostics, pg_stat_statements, log drains, and alerting.
Debugs failed Render deployments by analyzing logs, metrics, and database state. Identifies errors like missing env vars, port binding, OOM and suggests fixes for service crashes, health check failures, or performance issues.