[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M76HMA0S19Z2M3ZXMZARGAD4":3,"skill-same:01M76HMA0S19Z2M3ZXMZARGAD4":54},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M76HMA0S19Z2M3ZXMZARGAD4","insforge-debug",null,"Use when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx\u002F5xx, gateway timeout 502\u002F503\u002F504, edge function failure or timeout, login\u002FOAuth\u002Fauth errors, RLS denial, realtime channel issues, slow query on one endpoint, edge function or Vercel deploy failure), proactive audits (security\u002FRLS review, performance\u002Findex review, system health check, pre-launch readiness), or when the user has an error but doesn't know where to start.","bg-szy\u002FTOP-SKILLS","bg-szy","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F106576190?v=4","01M73A4E8KPV67SFXRY8XZGNBX","ShuZhiyong","01M73A4E96MQ294MHM74TZBVQD",6,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fmarketplace\u002Finsforge-debug\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: insforge-debug\ndescription: >-\n  Use when diagnosing problems in an InsForge project — reactive failures (SDK\n  error object, HTTP 4xx\u002F5xx, gateway timeout 502\u002F503\u002F504, edge function failure\n  or timeout, login\u002FOAuth\u002Fauth errors, RLS denial, realtime channel issues,\n  slow query on one endpoint, edge function or Vercel deploy failure), proactive\n  audits (security\u002FRLS review, performance\u002Findex review, system health check,\n  pre-launch readiness), or when the user has an error but doesn't know where\n  to start.\nlicense: Apache-2.0\n---\n\n# InsForge Debug\n\nDiagnose 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:\n\n1. A reference per **debug primitive** (one observability surface each — under `references\u002F`)\n2. **Symptom Recipes** (below) that name the primitive sequence for known reactive symptoms and proactive audits\n\n**Always use `npx -y @insforge\u002Fcli`** — never install the CLI globally.\n\n## Fastest Path: AI-Assisted Triage\n\nWhen 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.\n\n```bash\nnpx -y @insforge\u002Fcli diagnose --ai \"\u003Cissue description>\"\n```\n\nSee [references\u002Fai-assisted.md](references\u002Fai-assisted.md) for when to use this first vs when to skip, and how to verify the output.\n\n## Debug Primitives\n\nEach primitive is one independently-queryable observability surface backed by a distinct underlying data source. Real diagnoses are compositions of primitives.\n\nAll commands run via `npx -y @insforge\u002Fcli ...`. 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`).\n\n| Primitive (command) | What you see | Reference |\n|---------------------|-------------|-----------|\n| **Logs** (`logs \u003Csource>`; `diagnose logs` for cross-source aggregate) | Time-stream of events from 5 backend sources (`insforge.logs` \u002F `postgREST.logs` \u002F `postgres.logs` \u002F `function.logs` \u002F `function-deploy.logs`) | [references\u002Flogs.md](references\u002Flogs.md) |\n| **Metrics** (`diagnose metrics`) | EC2 instance time-series (CPU \u002F memory \u002F disk \u002F network) over `1h` \u002F `6h` \u002F `24h` \u002F `7d` | [references\u002Fmetrics.md](references\u002Fmetrics.md) |\n| **DB health** (`diagnose db`) | Current Postgres state via 7 named checks (`connections` \u002F `slow-queries` \u002F `bloat` \u002F `size` \u002F `index-usage` \u002F `locks` \u002F `cache-hit`) | [references\u002Fdb-health.md](references\u002Fdb-health.md) |\n| **Advisor** (`diagnose advisor --json`) | Static-scan issues across 3 categories (`security` \u002F `performance` \u002F `health`) with `ruleId` \u002F `affectedObject` \u002F `recommendation` | [references\u002Fadvisor.md](references\u002Fadvisor.md) |\n| **Policies** (`db policies`) | Active RLS rules from `pg_policies` (USING \u002F WITH CHECK per cmd per role) — returns all policies as a dump | [references\u002Fpolicies.md](references\u002Fpolicies.md) |\n| **Metadata** (`metadata --json`) | Declarative backend state dump (auth config \u002F tables \u002F buckets \u002F functions \u002F AI models \u002F realtime channels) | [references\u002Fmetadata.md](references\u002Fmetadata.md) |\n| **Error objects** (no command — read SDK \u002F HTTP response) | SDK error envelope + HTTP status — the routing table from a client-visible error to the right log source | [references\u002Ferror-objects.md](references\u002Ferror-objects.md) |\n| **Deploy state** (`deployments list` + `deployments status \u003Cid> --json` + `logs function-deploy.logs`) | Frontend (Vercel) deployment history + per-deploy metadata, plus edge function deploy logs | [references\u002Fdeploy-state.md](references\u002Fdeploy-state.md) |\n| **AI assist** (`diagnose --ai \"\u003Cdescription>\"`) | LLM agent that combines the other primitives — returns a diagnosis with suggestions | [references\u002Fai-assisted.md](references\u002Fai-assisted.md) |\n\n## Symptom Recipes\n\nEach 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.\n\n### Recipe: SDK returned `{ data: null, error: { code, message } }`\n\n1. **error-objects** — read code\u002Fmessage\u002Fdetails. If code starts with `PGRST*`, route by prefix using the table in the reference.\n2. **logs** (matching source per error-objects routing) — find the error timestamp, get the full backend-side context.\n3. **db-health** (`connections`, `locks`, `slow-queries`) — only if the error suggests DB issue (PostgREST timeout, lock conflict).\n\n### Recipe: HTTP 4xx\u002F5xx response on a specific request\n\n1. **error-objects** — use the HTTP status routing table to pick the log source (each status has a distinct path; 429 is special).\n2. **logs** (right source for that status) — find the failing request line and error.\n3. **metrics** — only for 5xx patterns spanning multiple endpoints, to confirm system-wide load issue.\n\n### Recipe: RLS access issue (403 on write, or empty result on read)\n\n> Same bug, two surfacings. Writes (INSERT \u002F UPDATE \u002F 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.\n\n1. **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.\n2. **policies** — list policies for that table; walk USING \u002F WITH CHECK against the actual request and the JWT claim used.\n3. **metadata** — verify auth config (which claim feeds `auth.uid()` \u002F `requesting_user_id()`; for third-party auth like Clerk\u002FAuth0, is the provider registered as a JWT issuer?).\n4. **db query** (`db query \"\u003Csql>\"`) — *empty-result variant only*: confirm rows that *should* be visible actually exist by querying as service role (not as the user): `npx -y @insforge\u002Fcli db query \"SELECT id, user_id FROM \u003Ctable>\"`. Distinguishes \"RLS filtered everything\" from \"no matching data exists\".\n\n### Recipe: Login fails \u002F OAuth callback errors \u002F token expired\n\n1. **logs** (`insforge.logs`) — find auth errors with timestamp and provider context.\n2. **metadata** — verify the provider is enabled, redirect URLs match the callback URL exactly (protocol + host + path).\n\n### Recipe: Edge function runtime error \u002F timeout\n\n1. **logs** (`function.logs`) — get the error stack and execution context.\n2. **metadata** — confirm the function exists and `status: \"active\"`.\n3. (If needed) `npx -y @insforge\u002Fcli functions code \u003Cslug>` — inspect the source for obvious issues.\n\n### Recipe: `functions deploy` failed\n\n1. **deploy-state** (`function-deploy.logs`) — find the build\u002Fpush error.\n2. **metadata** — confirm whether the function ended up in the active list (partial-deploy detection).\n\n### Recipe: `deployments deploy` failed (Vercel)\n\n1. **deploy-state** (`deployments list` + `status \u003Cid> --json`) — read `status`, `metadata.webhookEventType`, and `envVarKeys`.\n2. **Local** `npm run build` — reproduce the same error locally for faster iteration.\n\n### Recipe: Single slow query \u002F one endpoint slow\n\n1. **logs** (`postgres.logs`) — find the query text and timestamp.\n2. **db-health** (`slow-queries`, `index-usage`) — `slow-queries` only catches it while still running (>5s snapshot); check `index-usage` for a missing index. Already finished? **advisor** (`--category performance --json`) has the `pg_stat_statements` text + mean time; step 1 has the timestamp.\n3. **policies** — if it's an RLS-gated table, verify the policy isn't adding hidden joins.\n\n### Recipe: \"Memory is at ~80% but nothing is slow\"\n\n1. **Expected — say so first.** A dedicated Postgres instance turns idle RAM into shared buffers\n   and page cache; steady high memory with little traffic is its healthy state, not a leak\n   ([references\u002Fmetrics.md](references\u002Fmetrics.md), \"Memory: high is normal\").\n2. **metrics** (`--range 24h`) — only a *rising* trend or OOM kills\u002Frestarts change the answer.\n   OOM evidence lives in `postgres.logs` as the crash-recovery aftermath (\"terminating connection\n   because of crash of another server process\" \u002F \"automatic recovery in progress\").\n3. With OOM evidence, the fix is headroom: upgrade to a paid plan and pick a larger instance size\n   (dashboard → Project Settings → Compute & Disk). OOM on the smallest instances under real load is common and\n   expected — never \"restart to free memory\".\n\n### Recipe: All responses slow \u002F high CPU\u002Fmemory (active incident)\n\n1. **metrics** (`--range 1h`) — confirm system-wide pressure (CPU \u002F memory \u002F disk).\n2. **db-health** — DB is the most common bottleneck; check `connections`, `locks`, `slow-queries`.\n3. **logs** (`diagnose logs` aggregate) — error patterns across sources at the spike timestamp.\n4. **advisor** (`--severity critical`) — pre-existing known issues that may explain the degradation.\n\n### Recipe: Realtime channel won't connect \u002F messages missing\n\n1. **logs** (`insforge.logs`) — WebSocket errors and subscription failures.\n2. **metadata** — verify the channel pattern matches what the client subscribes to, `enabled: true`.\n3. **policies** — RLS on the underlying table (realtime delivers row changes; RLS gates which rows the subscriber sees).\n\n### Recipe: 429 rate limit\n\n1. **error-objects** — confirm 429 status. **No logs are recorded for 429s; no `Retry-After` header is returned.** Don't waste time grepping logs.\n2. **metrics** (`--range 1h`) — overall backend load context.\n3. **Fix is always client-side**: debounce, batch, exponential backoff, eliminate retry loops.\n\n### Recipe: Gateway timeout (502 \u002F 503 \u002F 504) on a specific URL\n\nRoute by URL subsystem before drilling:\n\n| URL pattern | Drill into |\n|-------------|-----------|\n| `\u002Fapi\u002Fdatabase\u002Frecords\u002F...` | **logs** (`postgREST.logs` → `postgres.logs`) + **db-health** (`locks`, `slow-queries`) |\n| `\u002Ffunctions\u002F\u003Cslug>` | **logs** (`function.logs`) — function may be crash-looping |\n| `\u002Fapi\u002Fauth\u002F...` | **logs** (`insforge.logs`) |\n| Any path during system-wide spike | **metrics** (`--range 1h`) |\n\n**504s across *unrelated* paths on a small instance: suspect OOM first.** Intermittent gateway\ntimeouts hitting database, auth, and functions alike are the classic out-of-memory signature on\nthe smallest instance sizes: the kernel kills Postgres, every in-flight request times out at the\ngateway while crash recovery runs, and it repeats on the next load spike.\n\n**Fast path: `npx -y @insforge\u002Fcli diagnose incident`** (Platform login required). The report is\nbuilt entirely on the cloud side — Prometheus scrape history, platform records, an outbound\ndatabase probe — so it works **even while the instance is down or wedged**, exactly when\n`diagnose logs` stops answering. It returns a verdict (`oom_likely`,\n`platform_operation_in_progress`, `paused_or_suspended`, `metrics_stopped`, `down_unknown`,\n`no_incident_detected`) with the evidence and the recommended action; `oom_likely` already means\nthe restart\u002Fmemory correlation checks below passed on the platform side.\n\nIf the command is unavailable (older CLI\u002Fbackend, `--api-key` link mode), confirm manually in\n**logs** (`postgres.logs`) via the crash-recovery aftermath — \"terminating connection because of\ncrash of another server process\" \u002F \"automatic recovery in progress\" — **time-correlated with the\n5xx burst**: recovery evidence alone only proves an unclean Postgres restart, so the timestamps\nmust line up before OOM becomes the leading diagnosis\n([references\u002Fmetrics.md](references\u002Fmetrics.md)). With that evidence the fix is headroom, not a\nretry loop:\n\n1. **Upgrade the instance** — `npx -y @insforge\u002Fcli projects upgrade-instance \u003Ctype>`\n   (`nano` → `micro` → `small` → `medium` → `large` → `xl`), or dashboard → Project Settings →\n   Compute & Disk. On the free plan, upgrade to a paid plan first, then pick the size. The\n   resize changes the bill and the CLI asks for interactive confirmation — get the user's\n   go-ahead first, then run unattended with the CLI-level `--yes` (the `-y` in `npx -y` is\n   npm's install flag, not the confirm-skip). The resize is async — poll `projects get` until\n   `operation_status` clears before declaring the incident resolved.\n2. The resize **restarts the project as part of the change**, which also clears any wedged\n   state — there is no separate user-facing restart, and a bare restart would only buy minutes\n   before the next spike OOMs again. OOM under real load on the smallest sizes is common and\n   expected, not a bug.\n\n### Recipe: Pre-launch \u002F proactive audit\n\n> Requires Platform login (`npx -y @insforge\u002Fcli login`). **Not available when the project is linked via `--api-key`** — fall back to `db-health` + `policies` + `metadata` for a manual audit in that case.\n\n1. **advisor** — full scan, then `--severity critical` first, then warnings.\n2. **advisor** (`--category security`) — focus on security issues; cross-verify with **policies** (RLS coverage) and **metadata** (auth config, public buckets, secret presence).\n3. **advisor** (`--category performance`) — cross-verify with **db-health** (`slow-queries`, `index-usage`, `bloat`).\n4. **advisor** (`--category health`) — cross-verify with **metrics** (resource trends over `7d`).\n5. After fixes, re-run **advisor** and confirm `isResolved: true` for each addressed `ruleId`.\n\n### Recipe: Don't know where to start\n\n1. **ai-assisted** (`diagnose --ai \"\u003Cerror or URL>\"`) — get a starting hypothesis.\n2. **Verify** by re-checking the primitives the diagnosis names. Trust the primitive observations over the suggestion.\n\n## When the Root Cause Is InsForge Itself\n\nSome diagnoses end at an InsForge-side defect, not a project misconfiguration: a platform bug or regression, an SDK call that misbehaves, docs or a skill that contradict observed behavior, or a missing capability. A debug session is exactly where these get confirmed — report them while the evidence is in hand:\n\n```bash\nnpx -y @insforge\u002Fcli feedback --json \\\n  --type bug --component backend --area db \\\n  --title \"\u003Cone-line summary>\" \\\n  --detail \"\u003Cwhat happened vs expected, minimal repro>\" \\\n  --command \"\u003Cthe failing call>\" \\\n  --error \"\u003Cverbatim error from logs>\" \\\n  --workaround \"\u003Cwhat you did instead>\"\n```\n\nNo login required; common PII patterns (emails, credential\u002Fkey formats, public IPs, home-directory usernames) are redacted locally — pattern-based, so still keep user data out. Use `--component sdk --language \u003Clang>` for SDK defects; `--component docs` or `--component skills` with `--doc` and `--expected` when documentation contradicts reality; `--type feature-request` when the finding is \"not supported\". Then continue the user's task with the workaround — never block on the report, and never file feedback for problems in the user's own app code or config. Full flag reference: the **insforge-cli** skill's Feedback section.\n","# InsForge Debug\n\nDiagnose 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:\n\n1. A reference per **debug primitive** (one observability surface each — under `references\u002F`)\n2. **Symptom Recipes** (below) that name the primitive sequence for known reactive symptoms and proactive audits\n\n**Always use `npx -y @insforge\u002Fcli`** — never install the CLI globally.\n\n## Fastest Path: AI-Assisted Triage\n\nWhen 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.\n\n```bash\nnpx -y @insforge\u002Fcli diagnose --ai \"\u003Cissue description>\"\n```\n\nSee [references\u002Fai-assisted.md](references\u002Fai-assisted.md) for when to use this first vs when to skip, and how to verify the output.\n\n## Debug Primitives\n\nEach primitive is one independently-queryable observability surface backed by a distinct underlying data source. Real diagnoses are compositions of primitives.\n\nAll commands run via `npx -y @insforge\u002Fcli ...`. 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`).\n\n| Primitive (command) | What you see | Reference |\n|---------------------|-------------|-----------|\n| **Logs** (`logs \u003Csource>`; `diagnose logs` for cross-source aggregate) | Time-stream of events from 5 backend sources (`insforge.logs` \u002F `postgREST.logs` \u002F `postgres.logs` \u002F `function.logs` \u002F `function-deploy.logs`) | [references\u002Flogs.md](references\u002Flogs.md) |\n| **Metrics** (`diagnose metrics`) | EC2 instance time-series (CPU \u002F memory \u002F disk \u002F network) over `1h` \u002F `6h` \u002F `24h` \u002F `7d` | [references\u002Fmetrics.md](references\u002Fmetrics.md) |\n| **DB health** (`diagnose db`) | Current Postgres state via 7 named checks (`connections` \u002F `slow-queries` \u002F `bloat` \u002F `size` \u002F `index-usage` \u002F `locks` \u002F `cache-hit`) | [references\u002Fdb-health.md](references\u002Fdb-health.md) |\n| **Advisor** (`diagnose advisor --json`) | Static-scan issues across 3 categories (`security` \u002F `performance` \u002F `health`) with `ruleId` \u002F `affectedObject` \u002F `recommendation` | [references\u002Fadvisor.md](references\u002Fadvisor.md) |\n| **Policies** (`db policies`) | Active RLS rules from `pg_policies` (USING \u002F WITH CHECK per cmd per role) — returns all policies as a dump | [references\u002Fpolicies.md](references\u002Fpolicies.md) |\n| **Metadata** (`metadata --json`) | Declarative backend state dump (auth config \u002F tables \u002F buckets \u002F functions \u002F AI models \u002F realtime channels) | [references\u002Fmetadata.md](references\u002Fmetadata.md) |\n| **Error objects** (no command — read SDK \u002F HTTP response) | SDK error envelope + HTTP status — the routing table from a client-visible error to the right log source | [references\u002Ferror-objects.md](references\u002Ferror-objects.md) |\n| **Deploy state** (`deployments list` + `deployments status \u003Cid> --json` + `logs function-deploy.logs`) | Frontend (Vercel) deployment history + per-deploy metadata, plus edge function deploy logs | [references\u002Fdeploy-state.md](references\u002Fdeploy-state.md) |\n| **AI assist** (`diagnose --ai \"\u003Cdescription>\"`) | LLM agent that combines the other primitives — returns a diagnosis with suggestions | [references\u002Fai-assisted.md](references\u002Fai-assisted.md) |\n\n## Symptom Recipes\n\nEach 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.\n\n### Recipe: SDK returned `{ data: null, error: { code, message } }`\n\n1. **error-objects** — read code\u002Fmessage\u002Fdetails. If code starts with `PGRST*`, route by prefix using the table in the reference.\n2. **logs** (matching source per error-objects routing) — find the error timestamp, get the full backend-side context.\n3. **db-health** (`connections`, `locks`, `slow-queries`) — only if the error suggests DB issue (PostgREST timeout, lock conflict).\n\n### Recipe: HTTP 4xx\u002F5xx response on a specific request\n\n1. **error-objects** — use the HTTP status routing table to pick the log source (each status has a distinct path; 429 is special).\n2. **logs** (right source for that status) — find the failing request line and error.\n3. **metrics** — only for 5xx patterns spanning multiple endpoints, to confirm system-wide load issue.\n\n### Recipe: RLS access issue (403 on write, or empty result on read)\n\n> Same bug, two surfacings. Writes (INSERT \u002F UPDATE \u002F 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.\n\n1. **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.\n2. **policies** — list policies for that table; walk USING \u002F WITH CHECK against the actual request and the JWT claim used.\n3. **metadata** — verify auth config (which claim feeds `auth.uid()` \u002F `requesting_user_id()`; for third-party auth like Clerk\u002FAuth0, is the provider registered as a JWT issuer?).\n4. **db query** (`db query \"\u003Csql>\"`) — *empty-result variant only*: confirm rows that *should* be visible actually exist by querying as service role (not as the user): `npx -y @insforge\u002Fcli db query \"SELECT id, user_id FROM \u003Ctable>\"`. Distinguishes \"RLS filtered everything\" from \"no matching data exists\".\n\n### Recipe: Login fails \u002F OAuth callback errors \u002F token expired\n\n1. **logs** (`insforge.logs`) — find auth errors with timestamp and provider context.\n2. **metadata** — verify the provider is enabled, redirect URLs match the callback URL exactly (protocol + host + path).\n\n### Recipe: Edge function runtime error \u002F timeout\n\n1. **logs** (`function.logs`) — get the error stack and execution context.\n2. **metadata** — confirm the function exists and `status: \"active\"`.\n3. (If needed) `npx -y @insforge\u002Fcli functions code \u003Cslug>` — inspect the source for obvious issues.\n\n### Recipe: `functions deploy` failed\n\n1. **deploy-state** (`function-deploy.logs`) — find the build\u002Fpush error.\n2. **metadata** — confirm whether the function ended up in the active list (partial-deploy detection).\n\n### Recipe: `deployments deploy` failed (Vercel)\n\n1. **deploy-state** (`deployments list` + `status \u003Cid> --json`) — read `status`, `metadata.webhookEventType`, and `envVarKeys`.\n2. **Local** `npm run build` — reproduce the same error locally for faster iteration.\n\n### Recipe: Single slow query \u002F one endpoint slow\n\n1. **logs** (`postgres.logs`) — find the query text and timestamp.\n2. **db-health** (`slow-queries`, `index-usage`) — `slow-queries` only catches it while still running (>5s snapshot); check `index-usage` for a missing index. Already finished? **advisor** (`--category performance --json`) has the `pg_stat_statements` text + mean time; step 1 has the timestamp.\n3. **policies** — if it's an RLS-gated table, verify the policy isn't adding hidden joins.\n\n### Recipe: \"Memory is at ~80% but nothing is slow\"\n\n1. **Expected — say so first.** A dedicated Postgres instance turns idle RAM into shared buffers\n   and page cache; steady high memory with little traffic is its healthy state, not a leak\n   ([references\u002Fmetrics.md](references\u002Fmetrics.md), \"Memory: high is normal\").\n2. **metrics** (`--range 24h`) — only a *rising* trend or OOM kills\u002Frestarts change the answer.\n   OOM evidence lives in `postgres.logs` as the crash-recovery aftermath (\"terminating connection\n   because of crash of another server process\" \u002F \"automatic recovery in progress\").\n3. With OOM evidence, the fix is headroom: upgrade to a paid plan and pick a larger instance size\n   (dashboard → Project Settings → Compute & Disk). OOM on the smallest instances under real load is common and\n   expected — never \"restart to free memory\".\n\n### Recipe: All responses slow \u002F high CPU\u002Fmemory (active incident)\n\n1. **metrics** (`--range 1h`) — confirm system-wide pressure (CPU \u002F memory \u002F disk).\n2. **db-health** — DB is the most common bottleneck; check `connections`, `locks`, `slow-queries`.\n3. **logs** (`diagnose logs` aggregate) — error patterns across sources at the spike timestamp.\n4. **advisor** (`--severity critical`) — pre-existing known issues that may explain the degradation.\n\n### Recipe: Realtime channel won't connect \u002F messages missing\n\n1. **logs** (`insforge.logs`) — WebSocket errors and subscription failures.\n2. **metadata** — verify the channel pattern matches what the client subscribes to, `enabled: true`.\n3. **policies** — RLS on the underlying table (realtime delivers row changes; RLS gates which rows the subscriber sees).\n\n### Recipe: 429 rate limit\n\n1. **error-objects** — confirm 429 status. **No logs are recorded for 429s; no `Retry-After` header is returned.** Don't waste time grepping logs.\n2. **metrics** (`--range 1h`) — overall backend load context.\n3. **Fix is always client-side**: debounce, batch, exponential backoff, eliminate retry loops.\n\n### Recipe: Gateway timeout (502 \u002F 503 \u002F 504) on a specific URL\n\nRoute by URL subsystem before drilling:\n\n| URL pattern | Drill into |\n|-------------|-----------|\n| `\u002Fapi\u002Fdatabase\u002Frecords\u002F...` | **logs** (`postgREST.logs` → `postgres.logs`) + **db-health** (`locks`, `slow-queries`) |\n| `\u002Ffunctions\u002F\u003Cslug>` | **logs** (`function.logs`) — function may be crash-looping |\n| `\u002Fapi\u002Fauth\u002F...` | **logs** (`insforge.logs`) |\n| Any path during system-wide spike | **metrics** (`--range 1h`) |\n\n**504s across *unrelated* paths on a small instance: suspect OOM first.** Intermittent gateway\ntimeouts hitting database, auth, and functions alike are the classic out-of-memory signature on\nthe smallest instance sizes: the kernel kills Postgres, every in-flight request times out at the\ngateway while crash recovery runs, and it repeats on the next load spike.\n\n**Fast path: `npx -y @insforge\u002Fcli diagnose incident`** (Platform login required). The report is\nbuilt entirely on the cloud side — Prometheus scrape history, platform records, an outbound\ndatabase probe — so it works **even while the instance is down or wedged**, exactly when\n`diagnose logs` stops answering. It returns a verdict (`oom_likely`,\n`platform_operation_in_progress`, `paused_or_suspended`, `metrics_stopped`, `down_unknown`,\n`no_incident_detected`) with the evidence and the recommended action; `oom_likely` already means\nthe restart\u002Fmemory correlation checks below passed on the platform side.\n\nIf the command is unavailable (older CLI\u002Fbackend, `--api-key` link mode), confirm manually in\n**logs** (`postgres.logs`) via the crash-recovery aftermath — \"terminating connection because of\ncrash of another server process\" \u002F \"automatic recovery in progress\" — **time-correlated with the\n5xx burst**: recovery evidence alone only proves an unclean Postgres restart, so the timestamps\nmust line up before OOM becomes the leading diagnosis\n([references\u002Fmetrics.md](references\u002Fmetrics.md)). With that evidence the fix is headroom, not a\nretry loop:\n\n1. **Upgrade the instance** — `npx -y @insforge\u002Fcli projects upgrade-instance \u003Ctype>`\n   (`nano` → `micro` → `small` → `medium` → `large` → `xl`), or dashboard → Project Settings →\n   Compute & Disk. On the free plan, upgrade to a paid plan first, then pick the size. The\n   resize changes the bill and the CLI asks for interactive confirmation — get the user's\n   go-ahead first, then run unattended with the CLI-level `--yes` (the `-y` in `npx -y` is\n   npm's install flag, not the confirm-skip). The resize is async — poll `projects get` until\n   `operation_status` clears before declaring the incident resolved.\n2. The resize **restarts the project as part of the change**, which also clears any wedged\n   state — there is no separate user-facing restart, and a bare restart would only buy minutes\n   before the next spike OOMs again. OOM under real load on the smallest sizes is common and\n   expected, not a bug.\n\n### Recipe: Pre-launch \u002F proactive audit\n\n> Requires Platform login (`npx -y @insforge\u002Fcli login`). **Not available when the project is linked via `--api-key`** — fall back to `db-health` + `policies` + `metadata` for a manual audit in that case.\n\n1. **advisor** — full scan, then `--severity critical` first, then warnings.\n2. **advisor** (`--category security`) — focus on security issues; cross-verify with **policies** (RLS coverage) and **metadata** (auth config, public buckets, secret presence).\n3. **advisor** (`--category performance`) — cross-verify with **db-health** (`slow-queries`, `index-usage`, `bloat`).\n4. **advisor** (`--category health`) — cross-verify with **metrics** (resource trends over `7d`).\n5. After fixes, re-run **advisor** and confirm `isResolved: true` for each addressed `ruleId`.\n\n### Recipe: Don't know where to start\n\n1. **ai-assisted** (`diagnose --ai \"\u003Cerror or URL>\"`) — get a starting hypothesis.\n2. **Verify** by re-checking the primitives the diagnosis names. Trust the primitive observations over the suggestion.\n\n## When the Root Cause Is InsForge Itself\n\nSome diagnoses end at an InsForge-side defect, not a project misconfiguration: a platform bug or regression, an SDK call that misbehaves, docs or a skill that contradict observed behavior, or a missing capability. A debug session is exactly where these get confirmed — report them while the evidence is in hand:\n\n```bash\nnpx -y @insforge\u002Fcli feedback --json \\\n  --type bug --component backend --area db \\\n  --title \"\u003Cone-line summary>\" \\\n  --detail \"\u003Cwhat happened vs expected, minimal repro>\" \\\n  --command \"\u003Cthe failing call>\" \\\n  --error \"\u003Cverbatim error from logs>\" \\\n  --workaround \"\u003Cwhat you did instead>\"\n```\n\nNo login required; common PII patterns (emails, credential\u002Fkey formats, public IPs, home-directory usernames) are redacted locally — pattern-based, so still keep user data out. Use `--component sdk --language \u003Clang>` for SDK defects; `--component docs` or `--component skills` with `--doc` and `--expected` when documentation contradicts reality; `--type feature-request` when the finding is \"not supported\". Then continue the user's task with the workaround — never block on the report, and never file feedback for problems in the user's own app code or config. Full flag reference: the **insforge-cli** skill's Feedback section.\n",{"name":5,"license":15,"description":7},"master","fd76f882a04e445e899d5cfb2732f2105ea054ee","skills\u002Fmarketplace\u002Finsforge-debug",0,"https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS","https:\u002F\u002Fbg-szy.github.io\u002FTOP-SKILLS\u002F","https:\u002F\u002Fgithub.com\u002Fbg-szy","https:\u002F\u002Fwww.ecust.edu.cn\u002F","a student of East China University of Science and Technology","2026-11-15 03:38:02",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add bg-szy\u002FTOP-SKILLS --skill insforge-debug",{"tool":40,"command":41},"bunx","bunx skills add bg-szy\u002FTOP-SKILLS --skill insforge-debug",{"tool":43,"command":44},"pnpm","pnpm dlx skills add bg-szy\u002FTOP-SKILLS --skill insforge-debug","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fmarketplace\u002Finsforge-debug\u002FSKILL.md",true,[48],{"path":49,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":52,"sourceHtmlUrl":53},"skill-report.json","REFERENCE","参考文档",114846,"https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fmarketplace\u002Finsforge-debug\u002Fskill-report.json",[55,64,71,78,85,92],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":59,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":63},"01M7DXW9N826PKXK174PVW3038","serpmaven","Scrape Google search results (SERP) to JSON with SERP Maven (serpmaven) - a real Chrome browser on a residential proxy with sticky sessions. Run it as a CLI, a Python library, a local HTTP search API (`serve`), an MCP server or a Docker image; set the proxy login, workers, pages and cost tracking. Use when the user wants Google results, rank tracking, a self-hosted SERP API, or live Google search for an AI agent.","MIT","https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fmarketplace\u002Fserpmaven\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":59,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":63},"01M7DXVHSTWDV65475QEQ915M7","revnu-landing-page-audit","Find out why a landing page isn't turning visitors into signups, demos or sales. Audits one page against what the ad, post or search that sends people there promised, then checks the first screen, proof, call to action, friction and mobile. Returns at most 7 prioritized fixes, plus what is fine and what could not be checked; rewrites specific lines and fixes the page in the repo when asked. Never promises a conversion lift. Works without a Revnu account. Use when the user says or asks: \"audit my landing page\", \"why isn't this page converting\", \"review my homepage\", \"my ads get clicks but no signups\", \"people bounce from the pricing page\", \"CRO review\", \"improve conversion rate\", \"is my hero section clear\", \"roast my landing page\", \"rewrite my headline\", \"what's wrong with this page\", \"landing page feedback\", \"make the signup page convert better\". Not for SEO or AI-search audits, page speed engineering on its own, or building a new page from scratch.","https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fmarketplace\u002Frevnu-landing-page-audit\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":59,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":63},"01M7DXV8X2D7B3VTD4HHYYHTGR","revnu-growth-context","Write down once who buys, what they're stuck on, what it costs, what proof you have and what you've already tried, so every growth task starts from facts instead of a questionnaire. Creates or updates .agents\u002Frevnu-growth.md from the repo, the live site and the user, and imports an existing product-marketing.md. Use when the user says \"set up our marketing context\", \"who is our ideal customer\", \"write our ICP\", \"describe the product for marketing\", \"positioning doc\", \"what's our brand voice\", \"remember this about our customers\", \"log what we tried\", \"what have we learned from marketing\", \"we changed pricing, update the context\", \"update our growth notes\", \"summarize the business for the agent\", \"import my product-marketing.md\", \"start a growth doc\", or before a first marketing, SEO, outreach or launch task when no context file exists. Works without a Revnu account.","https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fmarketplace\u002Frevnu-growth-context\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":59,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":63},"01M7DXV0DGJ1G0A60PAHC6J3C5","revnu-get-listed","Get onto the third-party pages AI answers and search cite when buyers ask for the best tool in your category: \"best X\" roundups, directories, review sites, GitHub awesome lists, community threads and comparison pages. Finds which ones are cited, ranks them by fit and effort, and drafts each submission, PR or pitch by the target's own rules. Use when the user says \"get us listed\", \"which directories should we submit to\", \"how do we get into best-of lists\", \"why does ChatGPT recommend competitors and not us\", \"get mentioned in AI answers\", \"submit to awesome lists\", \"get on G2\", \"where are our competitors listed\", \"pitch listicle authors\", \"find backlink opportunities\", \"launch directories\", \"get into roundups\", \"Product Hunt alternatives\", \"where should we be listed\", \"get cited by Perplexity\". Never submits, pays or posts without a yes. Works without a Revnu account.","https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fmarketplace\u002Frevnu-get-listed\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":59,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":63},"01M7DXTSPMGT9D6DSS0HP9BSTA","revnu-ai-readiness-audit","Audit whether your website gives ChatGPT, Perplexity, Claude, Gemini and Google's AI Overviews something worth quoting, and fix the pages that don't. Use when the user says or asks \"is my site ready for AI search\", \"audit my site for AI answers\", \"AEO audit\", \"GEO audit\", \"why doesn't ChatGPT quote our pricing\", \"make our pages citable by AI\", \"do I need llms.txt\", \"does schema help with ChatGPT\", \"check our structured data\", \"is our content visible without JavaScript\", \"AI SEO audit\", \"optimize our homepage for AI answers\", \"LLM SEO check\", \"why does AI get our product wrong\", \"fix our site for AI Overviews\". Checks fetchability and indexability, answers in the raw HTML, entity facts, schema (including JS-injected markup), headings, dates and llms.txt, then gives at most 10 prioritised fixes and edits the repo when asked. Works without a Revnu account.","https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fmarketplace\u002Frevnu-ai-readiness-audit\u002FSKILL.md",[],[],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":59,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":63},"01M7DXSZHCVTRS620GC3S97JZV","proxy-troubleshooting","Diagnose residential proxy failures, with NodeMaven's gateway as the reference - 407 with correct credentials, 406, 410, 500, a connection that hangs, ERR_TUNNEL_CONNECTION_FAILED in a browser, Playwright or Puppeteer ignoring proxy credentials, a sticky session that changes IP, geo-targeting that is silently ignored, passwords with special characters, and unexpected traffic from headless Chrome. Use when a proxy connection fails, returns the wrong location, or costs more traffic than expected.","https:\u002F\u002Fgithub.com\u002Fbg-szy\u002FTOP-SKILLS\u002Fblob\u002Fmaster\u002Fskills\u002Fmarketplace\u002Fproxy-troubleshooting\u002FSKILL.md",[],[]]