Insforge Debug
Diagnose InsForge SDK, HTTP, auth, RLS, realtime, edge, and deploy failures using CLI observability primitives and symptom recipes.
Overview
InsForge Debug is an agent skill most often used in Operate (also Ship, Build) that diagnoses InsForge failures and runs proactive audits using CLI observability primitives and symptom recipes.
Install
npx skills add https://github.com/insforge/agent-skills --skill insforge-debugWhat is this skill?
- Symptom Recipes map known failures to ordered debug primitive sequences
- Covers reactive issues: 4xx/5xx, 502–504, OAuth, RLS denial, realtime, slow queries, deploy failures
- Proactive audits: security/RLS, performance/index, system health, pre-launch readiness
- AI-assisted triage via npx @insforge/cli diagnose with verification against primitives
- Always uses npx @insforge/cli—never global CLI install
- Debug primitives documented per observability surface under references/
- Skill version metadata: 2.0.0 (May 2026)
Adoption & trust: 9.2k installs on skills.sh; 27 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have an InsForge error, timeout, or auth failure and do not know which logs, policies, or deploy state to inspect first.
Who is it for?
Solo builders shipping on InsForge who need repeatable triage instead of random dashboard clicking.
Skip if: Projects not on InsForge or issues purely in unrelated frontend code with no backend surface.
When should I use this skill?
Diagnosing InsForge reactive failures, proactive security/performance/health audits, or when the user has an error but does not know where to start.
What do I get? / Deliverables
You follow a verified primitive sequence—or AI triage cross-checked against primitives—to isolate root cause and fix SDK, edge, RLS, or deploy issues.
- Verified root-cause diagnosis tied to cited primitives
- Audit findings for RLS, performance, or pre-launch readiness
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Production and staging failures are handled in Operate; this skill is the canonical triage shelf for InsForge-backed apps. Errors subphase covers reactive symptom diagnosis and unknown-root-cause investigations.
Where it fits
Trace SDK error objects and HTTP status when a new endpoint fails against InsForge.
Run proactive RLS and policy review before exposing new tables to clients.
Execute pre-launch readiness recipe covering health, indexes, and deploy state.
Follow Symptom Recipes for 502/503/504 or realtime channel failures in production.
Use metrics and db-health primitives during a slow-query incident on one endpoint.
How it compares
Use instead of generic stack-trace guessing when InsForge-specific logs, RLS, and edge deploy state are the signal.
Common Questions / FAQ
Who is insforge-debug for?
Indie builders and small teams running apps on InsForge who need structured reactive debugging and optional pre-launch audits.
When should I use insforge-debug?
In Operate when SDK errors, HTTP failures, auth, RLS, or realtime break; in Ship for security/RLS and pre-launch checks; in Build when edge deploy or integration tests fail against InsForge.
Is insforge-debug safe to install?
Check the Security Audits panel on this Prism page; the skill drives npx CLI access to your project observability—treat credentials and project access like production ops.
SKILL.md
READMESKILL.md - Insforge Debug
# 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 @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. ```bash npx @insforge/cli diagnose --ai "<issue description>" ``` See [references/ai-assisted.md](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 @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](references/logs.md) | | **Metrics** (`diagnose metrics`) | EC2 instance time-series (CPU / memory / disk / network) over `1h` / `6h` / `24h` / `7d` | [references/metrics.md](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](references/db-health.md) | | **Advisor** (`diagnose advisor --json`) | Static-scan issues across 3 categories (`security` / `performance` / `health`) with `ruleId` / `affectedObject` / `recommendation` | [references/advisor.md](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](references/policies.md) | | **Metadata** (`metadata --json`) | Declarative backend state dump (auth config / tables / buckets / functions / AI models / realtime channels) | [references/metadata.md](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](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](references/d