Should I optimize without profiling first?

No. The document states intuition about bottlenecks is wrong roughly 80% of the time and the methodology requires a profile-first workflow with one change at a time.

Does this skill cover benchmarking methodology?

No. Benchmark writing, `benchstat` setup, and `b.Loop()` (Go 1.24+) live in the `golang-benchmark` skill. This skill handles pattern selection once a bottleneck is already identified.

What dependencies does it require?

Only `benchstat` (`go install golang.org/x/perf/cmd/benchstat@latest`). `pprof`, `fgprof`, and OpenTelemetry appear as referenced diagnose tools, not required installs.

Memory

golang-performance

Try it

Map a profiled Go bottleneck to the right optimization pattern using a measure-first methodology.

What it does

Translates a measured Go bottleneck into the right optimization pattern using a measure-first methodology. Runs an iterative cycle of define metric, benchmark baseline, diagnose with pprof, apply one change, and compare with benchstat. Includes a decision tree that maps pprof signals (alloc_objects, CPU dominance, GC%, I/O blocks) to six deep-dive references: memory, CPU, I/O, runtime tuning, caching, production observability. Supports three modes: architectural review, hot-path review, sequential bottleneck optimization.

When to use it

Applying the right fix after pprof flags a hot spot
Reviewing a package for allocation, I/O, or concurrency anti-patterns
Reducing per-request allocations in a high-throughput service
Suggesting benchmarks during a performance code review

The skill document

Persona: You are a Go performance engineer. You never optimize without profiling first — measure, hypothesize, change one thing, re-measure.

Thinking mode: Use ultrathink for performance optimization. Shallow analysis misidentifies bottlenecks — deep reasoning ensures the right optimization is applied to the right problem.

Modes:

Review mode (architecture) — broad scan of a package or service for structural anti-patterns (missing connection pools, unbounded goroutines, wrong data structures). Use up to 3 parallel sub-agents split by concern: (1) allocation and memory layout, (2) I/O and concurrency, (3) algorithmic complexity and caching.
Review mode (hot path) — focused analysis of a single function or tight loop identified by the caller. Work sequentially; one sub-agent is sufficient.
Optimize mode — a bottleneck has been identified by profiling. Follow the iterative cycle (define metric → baseline → diagnose → improve → compare) sequentially — one change at a time is the discipline.

Dependencies:

benchstat: go install golang.org/x/perf/cmd/benchstat@latest

Go Performance Optimization

Core Philosophy

Profile before optimizing — intuition about bottlenecks is wrong ~80% of the time. Use pprof to find actual hot spots (→ See samber/cc-skills-golang@golang-troubleshooting skill)
Allocation reduction yields the biggest ROI — Go's GC is fast but not free. Reducing allocations per request often matters more than micro-optimizing CPU
Document optimizations — add code comments explaining why a pattern is faster, with benchmark numbers when available. Future readers need context to avoid reverting an "unnecessary" optimization

Rule Out External Bottlenecks First

Before optimizing Go code, verify the bottleneck is in your process — if 90% of latency is a slow DB query or API call, reducing allocations won't help.

Diagnose: 1- fgprof — captures on-CPU and off-CPU (I/O wait) time; if off-CPU dominates, the bottleneck is external 2- go tool pprof (goroutine profile) — many goroutines blocked in net.(*conn).Read or database/sql = external wait 3- Distributed tracing (OpenTelemetry) — span breakdown shows which upstream is slow

When external: optimize that component instead — query tuning, caching, connection pools, circuit breakers (→ See samber/cc-skills-golang@golang-database skill, Caching Patterns).

Iterative Optimization Methodology

The cycle: Define Goals → Benchmark → Diagnose → Improve → Benchmark

Define your metric — latency, throughput, memory, or CPU? Without a target, optimizations are random
Write an atomic benchmark — isolate one function per benchmark to avoid result contamination (→ See samber/cc-skills-golang@golang-benchmark skill)
Measure baseline — go test -bench=BenchmarkMyFunc -benchmem -count=6 ./pkg/... | tee /tmp/report-1.txt
Diagnose — use the Diagnose lines in each deep-dive section to pick the right tool
Improve — apply ONE optimization at a time with an explanatory comment
Compare — benchstat /tmp/report-1.txt /tmp/report-2.txt to confirm statistical significance
Commit — paste the benchstat output in the commit body so reviewers and future readers see the exact improvement; follow the perf(scope): summary commit type
Repeat — increment report number, tackle next bottleneck

Refer to library documentation for known patterns before inventing custom solutions. Keep all /tmp/report-*.txt files as an audit trail.

Decision Tree: Where Is Time Spent?

Bottleneck	Signal (from pprof)	Action
Too many allocations	`alloc_objects` high in heap profile	Memory optimization
CPU-bound hot loop	function dominates CPU profile	CPU optimization
GC pauses / OOM	high GC%, container limits	Runtime tuning
Network / I/O latency	goroutines blocked on I/O	I/O & networking
Repeated expensive work	same computation/fetch multiple times	Caching patterns
Wrong algorithm	O(n²) where O(n) exists	Algorithmic complexity
Lock contention	mutex/block profile hot	→ See `samber/cc-skills-golang@golang-concurrency` skill
Slow queries	DB time dominates traces	→ See `samber/cc-skills-golang@golang-database` skill

Common Mistakes

Mistake	Fix
Optimizing without profiling	Profile with pprof first — intuition is wrong ~80% of the time
Default `http.Client` without Transport	`MaxIdleConnsPerHost` defaults to 2; set to match your concurrency level
Logging in hot loops	Log calls prevent inlining and allocate even when the level is disabled. Use `slog.LogAttrs`
`panic`/`recover` as control flow	panic allocates a stack trace and unwinds the stack; use error returns
`unsafe` without benchmark proof	Only justified when profiling shows >10% improvement in a verified hot path
No GC tuning in containers	Set `GOMEMLIMIT` to 80-90% of container memory to prevent OOM kills
`reflect.DeepEqual` in production	50-200x slower than typed comparison; use `slices.Equal`, `maps.Equal`, `bytes.Equal`

Deep Dives

Memory Optimization — allocation patterns, backing array leaks, sync.Pool, struct alignment
CPU Optimization — inlining, cache locality, false sharing, ILP, reflection avoidance
I/O & Networking — HTTP transport config, streaming, JSON performance, cgo, batch operations
Runtime Tuning — GOGC, GOMEMLIMIT, GC diagnostics, GOMAXPROCS, PGO
Caching Patterns — algorithmic complexity, compiled patterns, singleflight, work avoidance
Production Observability — Prometheus metrics, PromQL queries, continuous profiling, alerting rules

CI Regression Detection

Automate benchmark comparison in CI to catch regressions before they reach production. → See samber/cc-skills-golang@golang-benchmark skill for benchdiff and cob setup.

Cross-References

→ See samber/cc-skills-golang@golang-benchmark skill for benchmarking methodology, benchstat, and b.Loop() (Go 1.24+)
→ See samber/cc-skills-golang@golang-troubleshooting skill for pprof workflow, escape analysis diagnostics, and performance debugging
→ See samber/cc-skills-golang@golang-data-structures skill for slice/map preallocation and strings.Builder
→ See samber/cc-skills-golang@golang-concurrency skill for worker pools, sync.Pool API, goroutine lifecycle, and lock contention
→ See samber/cc-skills-golang@golang-safety skill for defer in loops, slice backing array aliasing
→ See samber/cc-skills-golang@golang-database skill for connection pool tuning and batch processing
→ See samber/cc-skills-golang@golang-observability skill for continuous profiling in production

Questions people ask

Should I optimize without profiling first?: No. The document states intuition about bottlenecks is wrong roughly 80% of the time and the methodology requires a profile-first workflow with one change at a time.
Does this skill cover benchmarking methodology?: No. Benchmark writing, `benchstat` setup, and `b.Loop()` (Go 1.24+) live in the `golang-benchmark` skill. This skill handles pattern selection once a bottleneck is already identified.
What dependencies does it require?: Only `benchstat` (`go install golang.org/x/perf/cmd/benchstat@latest`). `pprof`, `fgprof`, and OpenTelemetry appear as referenced diagnose tools, not required installs.

Related skills

golang-benchmark

Measure Go performance with statistical rigor — write benchmarks, profile hot paths, and detect regressions before shipping.

31 installs

golang-troubleshooting

Systematic root-cause debugging for Go programs, from reproduction to verification.

24 installs

golang-how-to

Golang skills orchestrator — always active on any Golang coding, review, debug, or setup task. Reads the task context and loads the most relevant skills from samber/cc-skills-golang, often multiple at once: writing a gRPC service loads golang-grpc + golang-testing + golang-error-handling; debugging a panic loads golang-troubleshooting + golang-safety; auditing security loads golang-security + golang-lint + golang-safety. Also: disambiguates competing clusters when two skills seem to overlap (performance vs benchmark vs troubleshooting, samber/lo vs mo vs ro, DI cluster, safety vs security), and configures the project's agent-config file (CLAUDE.md, AGENTS.md, GEMINI.md, Cursor rules, or Copilot instructions) to force-trigger skills in a project (/golang-how-to configure).

5 installs