plain-optimize
Captures and analyzes performance traces to identify slow queries and N+1 problems. Use when a page is slow, there are too many queries, or the user asks about performance.
Best use case
plain-optimize is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Captures and analyzes performance traces to identify slow queries and N+1 problems. Use when a page is slow, there are too many queries, or the user asks about performance.
Teams using plain-optimize should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/plain-optimize/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How plain-optimize Compares
| Feature / Agent | plain-optimize | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Captures and analyzes performance traces to identify slow queries and N+1 problems. Use when a page is slow, there are too many queries, or the user asks about performance.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Performance Optimization Workflow
## 1. Capture and Analyze
Make a request with tracing enabled — returns structured JSON with query counts, duplicates, issues, and span tree:
```
uv run plain observer request /path
uv run plain observer request /path --user 1
uv run plain observer request /path --method POST --data '{"key": "value"}'
```
The `--user` flag accepts a user ID or email.
The JSON output includes:
- `response.status` — HTTP status code
- `trace.query_count` / `trace.duplicate_query_count` — query summary
- `issues` — pre-detected problems (duplicate queries, exceptions)
- `queries` — each unique query with count, total duration, and source locations
- `spans` — nested span tree showing the request flow
## 2. Identify Bottlenecks
Check the `issues` array first — duplicate queries are flagged automatically with source locations. Then review:
- N+1 queries (duplicate queries with count > 1)
- Slow database queries (high `total_duration_ms`)
- Missing indexes
- Unnecessary work in hot paths
## 3. Apply Fixes
- Add `select_related()` / `prefetch_related()` for N+1
- Add database indexes for slow queries
- Cache expensive computations
## 4. Verify Improvement
Re-run `uv run plain observer request /path` and compare `query_count`, `duplicate_query_count`, and `trace.duration_ms`.Related Skills
plainx-release
Releases plainx packages with version suggestions, changelog generation, and git tagging. Use when releasing a package to PyPI.
plain-upgrade
Upgrades Plain packages and applies required migration changes. Use when updating to newer package versions.
plain-postgres-doctor
Check overall database health — schema correctness and operational health. Use when asked to check the database, validate schema, optimize indexes, or diagnose Postgres problems.
plain-portal
Open a remote Python shell on a production machine via encrypted tunnel. Use when you need to inspect production data, debug issues, run queries, or transfer files.
plain-install
Installs Plain packages and guides through setup steps. Use when adding new packages to a project.
plain-guide
Answer questions about the Plain framework by researching docs and source code. Use when asked "how do I...", "does Plain support...", or "how does X work?" questions.
plain-bug
Submit a bug report for the Plain framework. Use when the user wants to report a bug, error, or unexpected behavior. Collects context and creates a GitHub issue.
release
Releases Plain packages with intelligent version suggestions and parallel release notes generation. Use when releasing packages to PyPI.
future
Navigate and manage the future/ directory — view dependency graphs, filter by arc, find unblocked futures, and identify what to work on next. Use when deciding what to work on, exploring planned work, or checking dependencies between futures.
Pricing Optimizer
Analyzes and optimizes pricing strategy using proven frameworks
Logistics Operations Optimizer
You are a logistics operations analyst. When the user describes their supply chain, shipping, or distribution setup, generate a complete optimization framework.
Fleet Management Optimizer
You are a fleet management analyst. Help the user optimize vehicle fleet operations, reduce costs, and improve utilization.