PBTune

Sysbench OLTP and TPC-H OLAP benchmark execution patterns, multi-instance PostgreSQL management, snapshot management, the full WorkloadOrchestrator pipeline, and performance measurement workflows. Use this skill when working on benchmark executors, evaluation pipeline, instance management, snapshot restoration, configuration application, restart policy, system metrics collection, or any code in src/benchmarks/, src/tuners/engine/, src/utils/applicator.py, or src/utils/environments/.

Complete codebase map for the PBT PostgreSQL tuning research project. Covers all source packages, file inventory with responsibilities, dependency relationships, data flow through the tuning pipeline, and navigation guide. Use this skill whenever you need to understand where code lives, how packages relate to each other, which file to modify for a given task, or when onboarding to the project. This is the first skill to consult when starting any new task in this repository.

Population-Based Training algorithm implementation patterns, evolutionary optimization conventions, and PBT-specific coding standards for the database tuning research project. Use this skill whenever working on PBT core logic, evolution, worker management, population management, scoring, normalization, convergence detection, exploit-explore mechanics, or any code in src/tuners/pbt/.

PostgreSQL configuration parameter (knob) tuning patterns, including parameter contexts (postmaster/sighup/user), knob space management, hardware-aware fractional normalization, safe bounds enforcement, and the knob tier system. Use this skill whenever working on knob configuration, parameter application, knob metadata, hardware-aware normalization, transfer learning via warm-start, or any code in src/knobs/, or src/utils/applicator.py.

Patterns for designing, executing, and analyzing reproducible scientific experiments in the database tuning domain. Covers multi-seed runs, baseline comparisons, BO comparisons, statistical reporting, and results directory structure. Use this skill when creating experiment scripts, setting up baselines, running multi-seed campaigns, comparing against Bayesian Optimization, computing improvement percentages, designing experiment protocols, or working on any experiment orchestration code.

Feature-driven scoring pipeline (scoring-v2) including the CompositeScorer, QuantileUtilityNormalizer, FeatureDrivenWeightModel, scoring policies (fixed_v1, feature_driven_v2), workload feature extraction, reliability gating, drift detection, and saturation expansion. Use this skill whenever working on score computation, metric normalization, metric weighting, scoring policies, workload features, calibration, rescoring, normalization drift, saturation detection, or any code in src/utils/scoring/, src/utils/metrics.py, or src/utils/calibration.py. Also use when debugging score values, investigating why a worker scored unexpectedly, or modifying the scoring contract.

Development workflow, CI gates, testing patterns, and contribution conventions for the PBT PostgreSQL tuning project. Covers make targets, pytest structure, ruff linting, mypy type checking, git branching, and commit conventions. Use this skill when running tests, fixing lint errors, adding new test files, setting up development environment, or preparing changes for commit.

Post-hoc comparative evaluation pipeline that compares PBT-tuned PostgreSQL configurations against defaults using Docker-isolated benchmarks and rigorous statistical analysis (Wilcoxon signed-rank, bootstrap CI, Holm correction, Cohen's d). Use this skill when working on the evaluation module, comparison reports, statistical testing, session loading, Docker evaluation containers, evaluation CLI, or any code in src/evaluation/. Also use when running `python -m src.evaluation`, interpreting comparison results, or debugging evaluation failures.

Post-hoc knob importance analysis using fANOVA and TreeSHAP, data-driven tier generation via Jenks Natural Breaks, and hardware-aware importance validation across multiple physical machines. Use this skill when working on knob importance analysis, fANOVA, SHAP values, tier generation, importance ranking, cross-hardware validation, or designing the analysis pipeline for determining which PostgreSQL knobs matter most for performance tuning.

DatabaseEnvironment abstraction layer for PostgreSQL instance lifecycle management. Covers Docker and bare-metal backends, environment factory, instance creation/teardown, configuration application, health checks, and resource isolation. Use this skill when working on Docker containers, bare-metal PostgreSQL instances, environment selection, instance management, port allocation, or any code in src/utils/environments/.

Fair comparison methodology, controlling for hardware, citing published baselines, statistical significance in benchmarks. Use when designing experiments that compare systems or algorithms, or when reviewing benchmark results for publication.

LaTeX conventions, paper structure (IMRaD), citation management, related work synthesis. Use when drafting papers, formatting LaTeX, or writing academic content.

How to structure .claude/, CLAUDE.md, agent modes, instruction files, and skill directories for maximum AI agent effectiveness. Use when setting up a new project for AI-assisted development, configuring agent behavior, or organizing skills and instructions across multiple agents.

Perform code reviews. Use when reviewing pull requests, examining code changes, or providing feedback on code quality. Covers security, performance, testing, scientific reproducibility, and design review.

ETL patterns, data validation, schema evolution, CSV/JSON processing pipelines. Use when building data ingestion, transformation, or loading workflows, or when reviewing data processing code.

README standards, API docs, architecture decision records (ADRs), inline doc conventions. Use when formalizing documentation standards or writing technical docs.

Reproducibility checklist, seed management, hardware logging, results schema design. Use when setting up experiment tracking or managing complex run structures.

Find bugs, security vulnerabilities, and code quality issues. Use when asked to review changes, find bugs, perform security review, or audit code.

ALWAYS use this skill when committing code changes. Creates commits following conventional commit format. Trigger on any commit, git commit, save changes, or commit message task.

HPO taxonomy (grid, random, Bayesian, evolutionary, PBT), search space design, evaluation protocols. Use when implementing or reviewing optimization algorithms.

Systematic search strategy, inclusion/exclusion criteria, evidence synthesis, gap identification. Use when searching for papers, summarizing related work, or structuring a literature review.

Academic figure standards using matplotlib, color accessibility, DPI settings, LaTeX integration. Use when creating charts, plots, and figures for publication.

Prompt design patterns, chain-of-thought, few-shot, structured output, context window management. Use when crafting prompts for LLMs, designing system prompts, building agent instructions, or optimizing prompt quality.

Extract method, replace conditional with polymorphism, introduce parameter object, dependency injection. Use when cleaning up messy code, addressing technical debt, or doing large scale refactors.

ML reproducibility checklist, hardware specs, data versioning, code archival. Use prior to publishing code, sending a paper for review, or finalizing an experiment setup.

Publication-quality visualization patterns using matplotlib for convergence curves, worker trajectories, performance breakdowns, population diversity plots, and BO comparison charts. Use this skill when creating visualizations, plots, figures for the paper, analyzing results JSON files, rendering multi-seed error bands, or designing any figure for academic publication or presentation.

Scikit-learn model fitting, feature importance, cross-validation, SHAP integration. Use when training models, analyzing feature contributions, interpreting ML results, or evaluating model performance.

Exception hierarchies, retry patterns, graceful degradation, structured error logging. Use when standardizing error handling or improving robustness.

Testing best practices and conventions using pytest. Use when generating tests, configuring conftest.py, mocking, evaluating testing practices, or dealing with large test suites.

Guidelines for Python project structure, types, formatting, and docstrings. Use when starting new python components, analyzing architecture, or reviewing code quality.

Work plan tracking, dependency management, milestone planning, reviewer response strategy. Use when organizing research timelines, tracking experiment progress, planning thesis or paper milestones, or preparing reviewer rebuttals.

Statistical analysis practices, hypothesis testing, effect sizes, non-parametric tests, multiple comparison correction. Use when analyzing experiment results or running statistical tests.