go-benchmark

Measure and compare Go benchmarks or profiles; not PR review or optimization.

SKILL.md

GitHub

Go Benchmark

Measure a named Go behavior under controlled conditions. Return evidence for a performance claim rather than assuming that fewer allocations or shorter code makes the product faster.

Route precisely

  • Use when asked to design/write a benchmark, measure a hot path, interpret an existing profile, or compare named implementations.
  • Use code-review for potential defects in a diff, debugging-and-error-recovery for an unexplained failing or hanging program, and prove-checks for whether a passing check can detect its claimed defect.
  • Keep production optimization, dependency installation, release publication, and CI authoring outside this workflow unless separately requested. Do not launch agents or create worktrees automatically.

Establish the experiment

  1. Read repository instructions, working-tree state, go.mod/go.work, benchmark source, and callers. Record revision/local changes, supported Go version, actual toolchain, OS/architecture, hardware, GOMAXPROCS, build flags/tags, data size, and relevant dependency/configuration versions.
  2. Name the operation, representative workload, metric, desired decision, and correctness invariant. Separate microbenchmark throughput/allocations from end-to-end latency or a product requirement. If target, fixture, or baseline is unknown, resolve it before expensive measurement.
  3. Inspect benchmark setup, timed work, input reuse, result consumption, parallelism, and possible compiler elimination. Use version-supported APIs; b.Loop requires a supporting toolchain. Keep setup outside timed work only when setup is outside the operation being claimed.
  4. Reuse existing benchmarks first. Write or change benchmark files only when requested or necessary within an authorized benchmark-writing task; otherwise propose the change. Do not modify production code to create a faster result.

Measure within a budget

Agree the measurement scope from the request and project conventions: named packages/cases, run count, duration, profile type, and artifact destination. Use a disposable output location and preserve the working checkout. Inspect any benchmark or setup that may contact services or modify data before running it; isolate side effects.

Select the exact benchmark and avoid unrelated tests when supported. For example, adapt go test -run '^$' -bench '^BenchmarkParse$' -benchmem -count=10 <package> to the actual package and budget; do not run this example literally with a placeholder. Verify that the intended benchmark emitted measurements. No matches, missing tools, skipped work, or a failed run is not a measured pass.

Run competing measurements serially on the same hardware and toolchain with the same fixture, settings, and benchmark harness. Preserve the exact baseline input and record order, warmup/cache state, and shared-machine noise. Re-measure the baseline under matching conditions when an old report used a different toolchain, machine, or workload. Do not attribute toolchain or fixture differences to the implementation.

Compare and diagnose

Use an existing version-identified benchstat or an equivalent documented analysis; do not install or upgrade it automatically. Compare repeated samples and report sample count, variance/uncertainty, statistical evidence when available, and effect size. A small p-value alone does not establish a practically useful improvement; an inconclusive result is valid.

Read references/measurement-checks.md for harness validity, profiles, and comparison pitfalls. Profile only the relevant workload and protect artifacts that may contain paths, symbols, or user data. Do not open a production profiling endpoint or expose a new one as a side effect of measurement.

If an optimization is later authorized, change one hypothesis at a time, verify the correctness invariant, and compare against the same baseline. Do not commit results, choose a winner automatically, or claim unchanged behavior from benchmark timing alone.

Report

Return the question and metric, run identities/environment, baseline and candidate definitions, exact commands and selected cases, correctness evidence, sample summary and uncertainty, artifact locations, unrun work, and limits.

Use one outcome: MEASURED_DIFFERENCE, NO_CLEAR_DIFFERENCE, or INCOMPARABLE. State direction and practical impact for a measured difference. Use INCOMPARABLE for mismatched environments/harnesses, empty selection, missing baseline, or invalid execution. Do not invent missing values or claim speedups from a single timing or a static code inspection.

Adapted and substantially rewritten from Samber's golang-benchmark and measurement guidance in golang-performance, under the bundled LICENSE.samber-cc-skills-golang.