insforge-backend-advisor

$2b

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.

npx @insforge/cli diagnose advisor

By default the latest scan summary plus up to 50 issues is shown. Narrow with --severity and --category:

# 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](#security-audit)

Advisor category=performance

Slow queries, indexes, bloat

[Performance Audit](#performance-audit)

Advisor category=health

Connections, locks, system metrics

[System Health Audit](#system-health-audit)

Symptom: "everything is slow", high CPU/memory, all responses slow

Backend-wide degradation

[System Health Audit](#system-health-audit)

Symptom: "this query is slow" (without a single failing URL)

Query-level performance

[Performance Audit](#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:

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:

npx @insforge/cli db policies

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

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:

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:

npx @insforge/cli diagnose advisor --category performance

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

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:

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:

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:

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:

npx @insforge/cli diagnose advisor --category health

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

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

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

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

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

npx @insforge/cli diagnose logs

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

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

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

# 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

# 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.