InsForge Backend Advisor

Proactive backend health auditing for InsForge projects. This skill drives the

diagnose advisor

scan — security misconfigurations, performance regressions, and system health issues — then pairs each issue category with hands-on commands to verify and reproduce findings before changing anything.

Always use
npx @insforge/cli
— never install the CLI globally.

When to Use This Skill vs

insforge-debug

You should be here when...	You should be in `insforge-debug` when...
Doing a periodic health check / pre-launch audit	A specific request just returned an error or unexpected status
Reviewing security posture (RLS, secrets, auth config)	A user can't log in / token expired / OAuth callback failing
Looking for slow queries, bloat, missing indexes proactively	A specific endpoint is slow right now and the user pasted the URL
Backend-wide degradation: high CPU/memory, all responses slow, connection pool exhausted, locks contending	A single request failed or timed out
"What's wrong with my backend?" without a concrete symptom	"Why did THIS request fail?" with a concrete symptom

If you're not sure which side you're on: a concrete error/URL/status code →

insforge-debug

. A general "look for problems" → here.

Run a Scan First

Every workflow in this skill starts from a fresh advisor scan. The scan aggregates checks across security, performance, and health categories and ranks each issue by severity.

bash

npx @insforge/cli diagnose advisor

By default the latest scan summary plus up to 50 issues is shown. Narrow with

--severity

and

--category

bash

# Only critical issues (start here in any audit)
npx @insforge/cli diagnose advisor --severity critical

# Security category only
npx @insforge/cli diagnose advisor --category security

# JSON for full issue payload (ruleId, affectedObject, recommendation, isResolved)
npx @insforge/cli diagnose advisor --json

Each issue object includes

ruleId

severity

category

title

description

affectedObject

, and

recommendation

. Read

affectedObject

to know which table/policy/secret/resource the issue is about before drilling in.

Note:
diagnose advisor
requires InsForge Platform login. It is not available on projects linked via
--api-key
.

Quick Triage

Match the issue's

category

(after running a scan) or the user's symptom (if they came in cold) to a deep-dive section.

Source	Maps to	Deep-dive section
Advisor `category=security`	RLS, exposed config, secrets	Security Audit
Advisor `category=performance`	Slow queries, indexes, bloat	Performance Audit
Advisor `category=health`	Connections, locks, system metrics	System Health Audit
Symptom: "everything is slow", high CPU/memory, all responses slow	Backend-wide degradation	System Health Audit
Symptom: "this query is slow" (without a single failing URL)	Query-level performance	Performance Audit

For a mixed report or a "what should I fix first?" question, work through critical issues across all categories before warnings.

Security Audit

Triggers: advisor issues with

category=security

, or a request like "review RLS", "audit auth config", "any secrets exposed?".

Steps

List security issues from the latest scan:

bash

npx @insforge/cli diagnose advisor --category security

For each RLS-related issue (
```
affectedObject
```
is a table name or policy), inspect the live policies on that table:

bash

npx @insforge/cli db policies

Verify the project's auth configuration matches expectation (providers enabled, redirect URLs, JWT settings):

bash

npx @insforge/cli metadata --json

For secrets-related issues, list current secrets (names only — values are not printed unless explicitly requested) and check for ones marked
```
--reserved
```
or with expired
```
--expires
```
:

bash

npx @insforge/cli secrets list --all

If an advisor
```
ruleId
```
flags exposure (e.g., public bucket holding sensitive data, RLS disabled on a user-data table), confirm the affected object's actual state before recommending a change — do not blindly apply advisor's recommendation.

Information gathered: active RLS policies, auth providers and redirect URLs, secret inventory, ground-truth state of every

affectedObject

flagged by advisor.

Performance Audit

Triggers: advisor issues with

category=performance

, or a request like "find slow queries", "do I have missing indexes?", "is my DB bloated?".

Steps

List performance issues:

bash

npx @insforge/cli diagnose advisor --category performance

Pull the full database performance picture — slow queries, index efficiency, bloat, cache hit ratio, size:

bash

npx @insforge/cli diagnose db --check slow-queries,index-usage,bloat,cache-hit,size

For a specific table flagged by
```
affectedObject
```
, inspect it directly with SQL:

bash

npx @insforge/cli db query "SELECT pg_size_pretty(pg_total_relation_size('<table>')) AS total_size, pg_size_pretty(pg_indexes_size('<table>')) AS indexes_size"

Cross-check against EC2 instance metrics — a "slow query" report can also be CPU/memory pressure, not the query itself:

bash

npx @insforge/cli diagnose metrics --range 6h

If the issue is index-related, look at actual index usage via postgres logs to see whether the missing index is being hit at runtime:

bash

npx @insforge/cli logs postgres.logs --limit 50

Information gathered: slow query plans, index usage, table bloat, cache hit ratio, current EC2 resource utilization, postgres query patterns.

System Health Audit

Triggers: advisor issues with

category=health

, or a request like "is my backend healthy?", "any locks?", "connection pool OK?", "EC2 looking right?".

Steps

List health issues:

bash

npx @insforge/cli diagnose advisor --category health

Run the full database health sweep — connections, locks, and other live state:

bash

npx @insforge/cli diagnose db --check connections,locks

Pull EC2 instance metrics over a meaningful window (default 1h; widen for trend):

bash

npx @insforge/cli diagnose metrics --range 24h

Aggregate error logs to see whether health issues correlate with recent error spikes:

bash

npx @insforge/cli diagnose logs

If connection-pool exhaustion or lock contention is flagged, drill into postgres logs around the scan time:

bash

npx @insforge/cli logs postgres.logs --limit 100

Information gathered: connection pool state, lock contention, CPU/memory/disk/network metrics with trend, error log summary, postgres-level activity.

Iteration Workflow

Advisor issues persist across scans until resolved (issue objects carry

isResolved

). The recommended audit loop:

Scan —
```
diagnose advisor --severity critical
```
to get the working set.
Drill — for each issue, use the relevant deep-dive section above to verify the live state matches advisor's report.
Decide — only proceed to a fix after you've confirmed the issue is real. Advisor surfaces rule violations; whether they're business-relevant is a judgment call.
Fix — apply the change (RLS edit, index, query rewrite, etc.) via the
```
insforge-cli
```
skill (
```
npx @insforge/cli ...
```
commands).
Re-scan — run
```
diagnose advisor
```
again. The fixed issue should appear with
```
isResolved: true
```
on the next scheduled scan, or drop off the active set.

Do not rely on the same scan twice across a fix — always re-scan after applying changes.

Command Quick Reference

Advisor scan

bash

npx @insforge/cli diagnose advisor [--severity critical|warning|info] [--category security|performance|health] [--limit <n>] [--json]

Default

--limit

is 50.

--json

returns scan summary + full issue objects (with

ruleId

recommendation

isResolved

Backend deep-dive

bash

# Database health checks
npx @insforge/cli diagnose db [--check connections,slow-queries,bloat,size,index-usage,locks,cache-hit]

# EC2 instance metrics
npx @insforge/cli diagnose metrics [--range 1h|6h|24h|7d] [--metrics <list>]

# Aggregate error logs from all sources
npx @insforge/cli diagnose logs [--source <name>] [--limit <n>]

# Postgres-level logs
npx @insforge/cli logs postgres.logs --limit 50

Supporting

bash

# Project metadata (auth config, tables, buckets, functions, RLS policies)
npx @insforge/cli metadata --json

# Live RLS policies
npx @insforge/cli db policies

# Ad-hoc SQL against the project
npx @insforge/cli db query "<sql>"

# Secrets inventory
npx @insforge/cli secrets list --all

For reactive debugging (a concrete error, status code, or failing URL), switch to

insforge-debug

insforge-backend-advisor

NPX Install

Tags

SKILL.md Content

InsForge Backend Advisor

When to Use This Skill vs
`insforge-debug`

Run a Scan First

Quick Triage

Security Audit

Steps

Performance Audit

Steps

System Health Audit

Steps

Iteration Workflow

Command Quick Reference

Advisor scan

Backend deep-dive

Supporting