Database
The user types /database and what is going on, in their own words. Pick the one investigation that fits, say why in a sentence, then do it. Works on any PostgreSQL host: Supabase, Neon, RDS, Cloud SQL or self-hosted.
The prompts are in references/prompts.md, generated from the prompt library. Read only the entries you are weighing; do not load all of them.
Pick one
Match their words to the closest row. Go straight to the narrow prompt; PG00 is only for a broad request with no single problem named.
| They describe | Start with | Only if needed |
|---|---|---|
| General health, "make it simpler", no one problem | PG00 |
Narrow to the strongest cause before changing anything |
| A figure doesn't match its original source | PG01 |
PG02, D02 |
| Data passes every check but looks wrong | PG02 |
PG01, D01 |
| Records merged, split or duplicated | PG03 |
D05 |
| Past reports change after corrections | PG04 |
D03 |
| Several writers, mysterious overwrites | PG05 |
R05 |
| Upserts of identical rows, heavy write volume | PG06 |
PG13 |
| A sprawling ingestion pipeline | PG07 |
PG05, PG08 |
| Retries or replays duplicate or lose data | PG08 |
R01, R06 |
| Triggers, functions and app code disagree | PG09 |
A02, PG05 |
| Too many tables, views, functions, triggers | PG10 |
PG11, PG12 |
| Materialized or copied data drifts from the raw facts | PG11 |
A04, PG06 |
| Agents or new people misread the schema | PG12 |
G01, PG10 |
| Cost, CPU, storage or bloat | PG13 |
P03, PG06 |
| What breaks as data or traffic grows | PG14 |
P05 |
| Could we rebuild or restore it | PG15 |
PG04, PG17 |
| Agents keep asking you to decide | PG16 |
M05, M07 |
| A migration or schema change about to ship | PG17 |
G02, I02 |
D, R, A, P, G, I and M IDs are investigations and thinking prompts from /engineer; their one-line summaries are at the end of references/prompts.md. Use one of them instead of a PG prompt when the routing table names it and it fits better, rather than running both.
If their words could mean two different jobs, ask the one question that separates them and stop. Otherwise do not interview them.
Then do it
- Session can reach the repo or database: say the pick in one or two sentences, then run that one investigation yourself, read-only. Bring back the evidence its entry asks for. Stop when the problem is proved, ruled out, or blocked, and name the blocker.
- Session can't reach them: give the copy-ready prompt (the prompt text, the mode line, then "Evidence I expect:" and the entry's evidence line) in one fenced
textblock, and stop. - Mention one "only if needed" follow-up only when the findings point there. Never run a second investigation unasked.
Safety
- Read-only means read-only: no writes to production data, schema, migrations, roles, secrets or infrastructure, even when a fix looks obvious. Propose the fix and wait for a clear yes.
EXPLAIN ANALYZEruns the statement. Use plainEXPLAINon anything that writes, and keep heavy scans and long locks off production.- Rebuilds, replays, pgTAP runs and migration tests go on a separate database the user names. If none exists, say so and stop at the plan.
- Redact credentials and personal data from what you report. Use the least-privileged connection available; never print a connection string.
- On Supabase, check the current official guidance before acting: RLS on exposed schemas,
SECURITY DEFINERfunctions and views, and differences between production, branches and local. If thesupabaseorpostgres-best-practicesskill is installed, follow its own instructions rather than quoting it from memory.
Tools
The tools in references/prompts.md (pg_stat_statements, Supabase Advisors, HypoPG, pgTAP, declarative schemas, the Supabase skills) are optional. Check whether one is installed or enabled before relying on it, and say "install separately" rather than implying it is there. Recommend a command; run it only if it is installed and the user agreed.
The reference is generated. After the library changes, rebuild it from the repo root with node kits/engineering-kit/scripts/build_database_references.mjs.