# Fix Slow Queries

Diagnoses slow PostgreSQL queries and fixes them with comparisons and regression tests.

- Repository: https://github.com/paperclipai/paperclip (109885 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add paperclipai/paperclip --skill fix-slow-queries -g -a claude-code -y`
Codex: `npx skills add paperclipai/paperclip --skill fix-slow-queries -g -a codex -y`
Cursor: `npx skills add paperclipai/paperclip --skill fix-slow-queries -g -a cursor -y`
Gemini CLI: `npx skills add paperclipai/paperclip --skill fix-slow-queries -g -a gemini-cli -y`

## Description

Diagnose and fix slow Paperclip PostgreSQL queries using Cloud and Neon evidence, local reproduction, performance and result comparisons, regression tests, and a PR with passing checks. Use for costly queries, repeated database work, or slow requests with a suspected database cause.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Fix Slow Queries

Deliver a measured improvement with preserved behavior and a reviewable PR whose
latest commit passes checks. A list of suspicious SQL or an unverified rewrite
is an intermediate result. Respect a narrower request for diagnosis only.

## 1. Establish the target and finish line

- Resolve the reported URL, environment, company/workspace, deployed revision,
  owning repository, and local checkout. Read its `AGENTS.md` and scoped rules.
  Paperclip and the private `paperclip-cloud` control plane have different rules.
- Work in a dedicated branch/worktree. Reuse suitable existing work; keep the
  checkout running a live server out of branch switching and benchmark setup.
- Select a bounded batch, usually the top two or three query families. Record
  deferred candidates so discovery does not turn into an unbounded rewrite.
- The finish line is: reproducible baseline, faster treatment, output/behavior
  proof, relevant regression coverage, and green checks on each final PR head.
  A concrete access or infrastructure blocker must be reported as incomplete.

## 2. Find the actual database and rank the work

Read [Cloud discovery](references/cloud-discovery.md) when starting from a hosted
workspace. Follow the chain from Paperclip Cloud fleet admin to the stack's Neon
project, branch, endpoint, database, and runtime role. Record the corresponding
application deployment and time window. Do not reuse IDs from a previous run.

Capture query text/fingerprint, calls, total execution time, mean time, rows,
and available I/O, temporary-file, and lock-wait evidence. Rank both expensive
individual calls and frequent work with high aggregate cost. Group variants by
their actual caller; do not add unrelated query means into an endpoint latency.

Keep three claims separate:

The rest: https://github.com/paperclipai/paperclip/blob/HEAD/.agents/skills/fix-slow-queries/SKILL.md