Go Optimizer

Audit a Go codebase, report what is slow or broken and why, agree a plan with the user, then fix it. Order: evidence, approval, edits. Optimizations in Go often change concurrency, error semantics, exported APIs or memory ownership, so nothing is edited before the user approves.

Workflow

1. Scope (quick)

• Find the root: go.mod (or go.work). Note Go version (go directive, go version), module path, main packages (cmd/), CGO use, target OS/arch.
• Run python <skill-dir>/scripts/audit.py <project-root> -- static scan of go.mod and .go sources (goroutine leaks, missing context, HTTP client/server timeouts, defer in loops, time.After in loops, regexp in functions, string concat in loops, fmt.Sprintf for SQL, ignored errors, unbounded goroutines) with file:line evidence. --json for post-processing.
• Classify the workload: CPU-bound, IO/network service, memory/GC-bound, startup/binary-size, or build-time. Advice differs. Ask which hurts if unclear.
• Read references/tooling.md once: which of pprof, go test -bench, benchstat, go tool trace, hyperfine are available.

2. Audit

The script finds cheap leads; you find the rest by reading the hot path. Read go.mod, main.go/server setup, the 3-5 handlers or functions the user cares about or a profile points at. Load only what applies:

Measure, never guess. Profile the real workload (CPU, heap alloc_space, goroutine, mutex/block) before editing; benchmark with -count >= 6 and compare with benchstat. If the workload can't be run or a tool is missing, say measurement wasn't possible instead of inventing numbers.

Mark each finding Confirmed (profile/code evidence) or Suspected (needs measuring).

3. Report

Fill assets/report-template.md, save as GO_OPTIMIZATION_REPORT.md in the project root, and show the user. 5-line summary, findings table by impact/effort, then per-finding detail (evidence, why it hurts, fix, risk, API impact). Group related findings.

4. Plan -- then stop for approval

Use plan mode: EnterPlanMode (load with ToolSearch if deferred), write the plan, present with ExitPlanMode; if unavailable show it in chat and wait for an explicit "go". Structure:

1. Quick wins -- server/client timeouts, sync.Pool-free fixes like make([]T, 0, n), strings.Builder, hoisting regexp.MustCompile, GOMEMLIMIT, build flags. Low risk.
2. Structural -- fix goroutine leaks and context propagation, bounded worker pools, batching queries, removing allocations on measured hot paths, lock redesign. Name each behaviour change.
3. Heavy -- PGO, dependency swaps (JSON, router), exported API changes, unsafe, architecture changes. Separately approved. Each step: files touched, expected effect, how to verify, how to roll back.

5. Fix

Only approved items, small groups. After each: gofmt -l ., go vet ./..., go build ./..., go test ./... (add -race where the project already runs it). A break must trace to one change. Don't mix a Go version / module upgrade with optimization edits. If something turns out riskier than planned (changed error semantics, exported signature, new data race), stop and ask.

6. Verify and wrap up

Re-measure with the same command and inputs: benchstat old.txt new.txt, p50/p99 latency and throughput under the same load, RSS / GC stats (GODEBUG=gctrace=1), binary size, build time. State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• Algorithm and I/O first. A missing index, an N+1, or an O(n^2) loop beats any allocation tweak.
• Allocations drive Go cost. Check alloc_space/alloc_objects and -gcflags=-m before rewriting; fix the top few sites.
• Don't reach for sync.Pool, unsafe or custom allocators first. Each adds bugs; require a benchmark.
• Every goroutine needs an exit. Leaks and unbounded fan-out are the common production failures; context cancellation must reach every blocking call.
• Timeouts everywhere. http.Server, http.Client, DB queries, outbound calls: defaults are "never".
• Readability stays. Idiomatic, simple Go beats clever; don't contort cold code.
• Docs move. Check go.dev/doc/ and pkg.go.dev for the toolchain/library version in go.mod, not memory.