oioio-space/unpixel / .claude/skills/go-benchmark
go-benchmark
VerifiedUse when writing Go benchmarks or when asked to measure/optimize/improve the performance of a function — establishes correct benchmarks, measures with -benchmem and pprof, optimizes hot paths, and proves the gain (and no regression) with benchstat.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.9 KB |
SKILL.md
View on GitHub---
name: go-benchmark
description: Use when writing Go benchmarks or when asked to measure/optimize/improve the performance of a function — establishes correct benchmarks, measures with -benchmem and pprof, optimizes hot paths, and proves the gain (and no regression) with benchstat.
---
# Go Benchmarking & Performance
Goal: **only optimize what's measured.** Write a correct benchmark, measure, optimize, and
**prove** the improvement with `benchstat` before/after.
## When to benchmark (the right targets)
Benchmark a function when: it's on a hot path (called in tight loops — e.g. the candidate-search
and image-distance core of the port), it allocates heavily, or someone claims it's "slow". Do NOT
micro-optimize cold code — clarity wins there (see go-style-guide).
## Writing a correct benchmark (Go 1.24+)
```go
func BenchmarkDistance(b *testing.B) {
img := loadFixture() // setup OUTSIDE the loop
b.ReportAllocs() // always report allocs
b.ResetTimer() // if setup was non-trivial
for b.Loop() { // Go 1.24+: not `for i := 0; i < b.N; i++`
sink = distance(img) // assign to a package-level sink…
}
}
var sink int // …to stop the compiler eliminating the call
```
- `b.Loop()` (Go 1.24+) — keeps setup/cleanup out of the timed region automatically.
- `b.ReportAllocs()` — allocs/op is usually the real lever.
- Prevent dead-code elimination: store results in a package-level `sink`.
- Table-driven sub-benchmarks with `b.Run(name, …)` for input sizes.
- `b.RunParallel` for contention; `b.SetBytes(n)` for throughput (MB/s).
## Measure
```bash
mise run bench # go test -bench -benchmem ./...
go test -bench=Distance -benchmem -cpuprofile cpu.prof -memprofile mem.prof ./internal/...
go tool pprof -top cpu.prof # find the hot frames / allocations
```
## Optimize (typical levers, cheapest first)
1. **Reduce allocations**: preallocate slices/maps with known size, reuse buffers
(`sync.Pool`, `bytes.Buffer`), avoid `[]byte`↔`string` copies (`strings.Builder`).
2. **Avoid reflection / interface boxing** on hot paths; use generics or concrete types.
3. **Hoist work out of loops**; precompute; use `slices`/`maps` helpers.
4. **Algorithmic** improvement (better complexity) beats micro-tuning — escalate to
`algo-architect` if the win is algorithmic.
## Prove the gain (mandatory)
```bash
mise run bench:baseline # save baseline BEFORE changing code
# …optimize…
mise run bench:compare # benchstat baseline vs new → shows %delta + significance
```
Keep a change only if `benchstat` shows a **statistically significant** improvement (and no
regression in allocs or other benchmarks). Commit the benchmark alongside the optimization.
## Notes
- Benchmark artifacts (`bench*.txt`, `*.prof`) are gitignored and cleaned by `repo-janitor`.
- Don't sacrifice clarity for a tiny gain — measure first, and only optimize where it matters.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |