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 max LIMIT and non-zero OFFSET for 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, no Seq Scan on large tables.
  • Draft the ## Database section from templates/query-plans.md with 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) (postgresai skill as source of truth in the monolith)
  • gitlab-org/ai/skills!152 (merged) (sync of postgresai from 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

  1. Install and authenticate the CLI: npm i -g postgresai && postgresai login, then postgresai set-default-project gitlab-production-main.
  2. 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.
  3. Confirm the agent loads gitlab-query-plans and postgresai, captures SQL through bin/rails runner, runs scripts/joe.sh explain, and shows the drafted ## Database section before touching the MR.
  4. bash .claude/skills/postgresai/tests/test_joe.sh
  5. bundle exec rspec spec/tooling/ai_harness/doctor/integration_spec.rb
  6. scripts/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.

Edited by SAM FIGUEROA

Merge request reports

Loading
Loading