insforge-debug
installsforks
How to install insforge-debug?
insforge/agent-skills/insforge-debug
$npx -y skills add insforge/agent-skills --skill insforge-debugUse 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 Verce
SKILL.md
| 1 | # InsForge Debug |
| 2 | |
| 3 | 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: |
| 4 | |
| 5 | 1. A reference per **debug primitive** (one observability surface each — under `references/`) |
| 6 | 2. **Symptom Recipes** (below) that name the primitive sequence for known reactive symptoms and proactive audits |
| 7 | |
| 8 | **Always use `npx @insforge/cli`** — never install the CLI globally. |
| 9 | |
| 10 | ## Fastest Path: AI-Assisted Triage |
| 11 | |
| 12 | 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. |
| 13 | |
| 14 | ```bash |
| 15 | npx @insforge/cli diagnose --ai "<issue description>" |
| 16 | ``` |
| 17 | |
| 18 | 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. |
| 19 | |
| 20 | ## Debug Primitives |
| 21 | |
| 22 | Each primitive is one independently-queryable observability surface backed by a distinct underlying data source. Real diagnoses are compositions of primitives. |
| 23 | |
| 24 | 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`). |
| 25 | |
| 26 | | Primitive (command) | What you see | Reference | |
| 27 | |---------------------|-------------|-----------| |
| 28 | | **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) | |
| 29 | | **Metrics** (`diagnose metrics`) | EC2 instance time-series (CPU / memory / disk / network) over `1h` / `6h` / `24h` / `7d` | [references/metrics.md](references/metrics.md) | |
| 30 | | **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) | |
| 31 | | **Advisor** (`diagnose advisor --json`) | Static-scan issues across 3 categories (`security` / `performance` / `health`) with `ruleId` / `affectedObject` / `recommendation` | [references/advisor.md](references/advisor.md) | |
| 32 | | **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) | |
| 33 | | **Metadata** (`metadata --json`) | Declarative backend state dump (auth config / tables / buckets / functions / AI models / realtime channels) | [references/metadata.md](references/metadata.md) | |
| 34 | | **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) | |
| 35 | | **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/deploy-state.md) | |
| 36 | | **AI assist** (`diagnose --ai "<description>"`) | LLM agent that combines the other primitives — returns a diagnosis with suggestions | [references/ai-assisted.md](references/ai-assisted.md) | |
| 37 | |
| 38 | ## Symptom Recipes |
| 39 | |
| 40 | 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. |
| 41 | |
| 42 | ### Recipe: SDK returned `{ data: null, error: { code, message } }` |
| 43 | |
| 44 | 1. **error-objects** — read code/message/details. If code starts with `PGRST*`, route by prefix using the table in the reference. |
| 45 | 2. **logs** (matching source per error-objects routing) — find the error timestamp, get the full backend-side context. |
| 46 | 3. **db-health** (`connections`, `locks`, `slow-queries`) — only if the error suggests DB issue (PostgREST timeout, lock conflict). |
| 47 | |
| 48 | ### Recipe: HTTP 4xx/5xx response on a specific request |
| 49 | |
| 50 | 1. **error-objects** — use the HTTP status routing table to pick the log source (each status has a distinct path; 429 is special). |
| 51 | 2. **logs** (right source for that st |
People who liked this also viewed
6 picksType
- azure-diagnosticsDebug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deploySkillsJul 2026
- systematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesSkillsJul 2026
- safe-debugRigor Debug / Rigor Audit skill for deep learning research work. Use when the user pastes a traceback, terminal error, CUDA OOM, checkpoint load failure, shape mismatch, NaN loss symptom, or training SkillsMay 2026
- explore-runRigor Improve / Rigor Explore run leaf skill for bounded exploratory evidence in deep learning research repositories. Use when the researcher explicitly authorizes exploratory runs such as small-subseSkillsMay 2026
- minimal-run-and-auditRigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation SkillsMay 2026
- fix-errorsFix compilation errors, linting issues, and test failures in the warp Rust codebase. Covers presubmit checks, WASM-specific errors, and running specific tests. Use when the user hits build errors, cliSkillsJul 2026
