Overview

Perf-baseline-manager handles storage and comparison of performance baselines. It enforces one baseline JSON per version and records both metrics and environment metadata. It aligns with the canonical contract in docs/perf-requirements.md.

How This Skill Works

It stores baselines at {state-dir}/perf/baselines/<version>.json and overwrites any prior file for that version. It records metrics and environment metadata and produces a minimal output with baseline_version, metrics, and file path.

When to Use It

• Consolidating perf results when multiple runs exist for a single version
• Locking in a baseline for a release by creating a single per-version JSON
• Comparing current metrics against a prior version baseline to detect regressions
• CI pipelines that must avoid duplicate baseline files for the same version
• Auditing environment metadata alongside performance metrics

Quick Start

1. Step 1: Produce a baseline payload with metrics and environment data per docs
2. Step 2: Save to {state-dir}/perf/baselines/<version>.json, overwriting any existing file
3. Step 3: Verify the output fields baseline_version, metrics, and file are correct

Best Practices

• Follow docs/perf-requirements.md as the canonical contract
• Always overwrite the old baseline when a new baseline for the same version is produced
• Ensure only one baseline JSON exists per version and store it at the exact path
• Store metrics alongside environment metadata for full traceability
• Validate the baseline file path and summary before distribution

Example Use Cases

• Baseline version 1.0.0 created after CI run with metrics and env data
• After optimization, updated baseline 1.0.1 to reflect improvements
• CI job outputs baseline.json at state-dir/perf/baselines and replaces older 0.9.9
• Compare 1.2.0 vs 1.1.9 to identify regressions
• Environment metadata captured: OS, CPU, tool versions, and hardware

Frequently Asked Questions