Add skill for generating query plans on merge requests
What does this MR do and why?
Adds the gitlab-query-plans agent skill at .claude/skills/gitlab-query-plans/. It guides a local agent (Claude Code, OpenCode via .agents/skills) through producing the raw SQL and Database Lab query plans that database review requires for new or modified queries.
The skill is a thin GitLab workflow on top of the postgresai skill (added in !260040 (merged)), which owns all CLI operations. This skill covers only what postgresai does not:
- Capture the final SQL that Rails runs (
references/capture-sql.md), one statement per variation, with maxLIMITand non-zeroOFFSETfor paginated queries. - Pick production IDs with enough data, starting from the well-known IDs in
database_review.md. - Check the plan the way a database reviewer does: rows at least equal to
LIMIT, cold timing reported first with reruns labeled warm, shared buffers hit/read, noSeq Scanon large tables. - Draft the
## Databasesection fromtemplates/query-plans.mdwith placeholder IDs in the SQL (the real query stays behind the postgres.ai console link), show it to the user, and update the MR only after approval.
Small reconciling edits to .claude/skills/postgresai/ so the two skills do not contradict each other: cold-first timing in references/plan-analysis.md, the console plan-link recipe in references/advanced.md, the db/docs to gitlab-production-<db> alias procedure (covering sec) in references/gitlab.md, and references/db-review-flow.md reduced to a pointer at this skill.
The skill needs a running GDK and an authenticated postgresai CLI, so its description tells Duo agent sessions not to load it.
References
- !260040 (merged) (
postgresaiskill as source of truth in the monolith) - gitlab-org/ai/skills!152 (merged) (sync of
postgresaifrom the monolith) doc/development/database_review.md,doc/development/database/query_performance.md,doc/development/database/database_lab.md
How to set up and validate locally
- Install and authenticate the CLI:
npm i -g postgresai && postgresai login, thenpostgresai set-default-project gitlab-production-main. - In a Claude Code or OpenCode session on this branch, ask for query plans for an MR that adds or changes a scope, for example
Ai::FlowTrigger.for_projects. - Confirm the agent loads
gitlab-query-plansandpostgresai, captures SQL throughbin/rails runner, runsscripts/joe.sh explain, and shows the drafted## Databasesection before touching the MR. bash .claude/skills/postgresai/tests/test_joe.shbundle exec rspec spec/tooling/ai_harness/doctor/integration_spec.rbscripts/ai_harness/doctor
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.