mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-07 06:16:06 -10:00
DottaandPaperclip
739f9e40a4
## Thinking Path > - Paperclip helps people manage agents that work across tasks and services. > - Slow pages and background work can come from expensive or repeated database queries. > - The query often starts in the Paperclip app while its evidence lives in Paperclip Cloud, Neon, and application logs. > - A useful fix must reproduce the slow SQL locally and preserve its complete results and user behavior. > - The procedure also needs to measure any exceptional migration on a database of realistic size. > - This pull request gives contributors a repeatable skill for that work and for carrying the fix through PR checks. > - The benefit is a clear, measured handoff with fewer query regressions and fewer risky migration proposals. ## Linked Issues or Issue Description **Issue type** Missing documentation. **Where is the issue?** `.agents/skills/` has no shared procedure for diagnosing and fixing slow Paperclip queries across Cloud and Neon. **What's wrong?** A contributor must reconstruct the path from a slow workspace to its database, capture the service's actual SQL, reproduce it locally, compare complete results, and track the PR through review and CI. That makes it easy to mistake cumulative statistics for a recent request trace or a faster but changed result for a valid fix. **Suggested fix** Add a project skill that covers discovery, baseline and treatment benchmarks, regression checks, migration constraints, and PR follow-through. Related work: #16278, #16286, and #16291 supplied the query cases and local benchmark lessons. No existing slow-query skill PR or issue appeared in the duplicate search. ## What Changed - Add `fix-slow-queries` with a bounded workflow from Cloud discovery to a reviewed PR. - Add references for locating the right Neon database and for measuring full service SQL against complete output comparisons on disposable PostgreSQL. - Require a serious reason for migrations, prohibit boot-time migration workarounds, and require production-size timing and escalation for slow migrations. ## Verification - Run the skill-creator `quick_validate.py` against `.agents/skills/fix-slow-queries`: passed. - Run `pnpm --filter @paperclipai/skills-catalog test`: 5 files, 20 tests passed, including the repo-wide skill-description budget check. - Check all five local Markdown links, metadata length, final newlines, and whitespace: passed. - Run `git diff --check`: passed. - Review the documented procedure against the cases in #16278, #16286, and #16291: baseline helper isolation, large JSON, older deep links, and latest-commit PR checks are covered. - This change adds instructions only. It changes no database schema or runtime behavior. ## Risks - Provider menus and private Cloud file locations may change. The skill requires contributors to verify the current stack mapping and owning repository before using them. - Synthetic benchmarks do not establish deployed latency. The skill requires a fresh deployed measurement when rollout is authorized. ## Model Used OpenAI GPT-6 via Codex, with tool use and code execution. The served model variant and context window were not exposed to this task. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <[email protected]>