Guides how Go reads to a human across two themes — identifier and structural naming (MixedCaps/mixedCaps never under_scores, initialisms kept as one case unit like URL/ID/HTTP, no Get prefix on getters, single-method interfaces get -er names, short scope-proportional variable and 1–2-letter receiver names that are never this/self, package names that are short lowercase nouns with no util/common grab-bags and no stutter, and the early-return line-of-sight shape) and exported doc comments (a full sentence beginning with the name being declared, one package comment, the Deprecated: convention, gofmt owns mechanical formatting). Auto-invokes when writing or editing identifier names, package names, receiver names, getters, initialisms like URL/ID, or exported doc comments — and on "is this named idiomatically", "rename this", or "clean up the naming". The name and its doc comment are the API a reader meets first.
The consolidated Go 1.21→1.26 feature reference and modernization rule — which idiom is available given the module's `go` directive, and prefer the modern builtin/stdlib form over the stale hand-rolled one. The `go` line gates which language features compile (range-over-func needs `go 1.23`, per-iteration loop variables need `go 1.22`), so "idiomatic" means *current* idiomatic for the declared version. Catches the pre-modern Go that older training data emits: the `tc := tc` loop copy (unneeded since 1.22), `for i := 0; i < b.N; i++` benchmarks (use `b.Loop`, 1.24), hand-rolled `min`/`max`/`Contains` (builtins/`slices`, 1.21), `omitempty` on `time.Time` (use `omitzero`, 1.24), the `errors.As` out-param dance (use `errors.AsType[T]`, 1.26), and the `tools.go` hack (use `tool` directives, 1.24). Auto-invokes when choosing a Go idiom that depends on version, setting or raising the `go` directive, modernizing old Go, or on "what version is this from" / "is there a newer way" questions.
Guides framing a Go performance decision by audience — the same change is right for one and wrong for another: the library author who can't profile callers and must not pessimize the common case (offer AppendXxx/[]byte forms, no unsafe in the API), the app developer who can profile and optimizes the proven hot path, the SRE who needs the code diagnosable (pprof labels, metrics, GOMEMLIMIT), the next reader who pays for clever micro-opts; the clarity-vs-speed through-line. Fires on "should a library do this", "is this worth optimizing for my users", "make this diagnosable", "premature optimization vs pessimization", "who am I optimizing for". Routes the policy root to go-idiomatic-discipline, measure-first to go-perf-methodology.
Guides reviewing Go for performance — flagging premature pessimization (free wins: prealloc a sized slice, strings.Builder over += in a loop, bounded fan-out) while NOT demanding premature optimization on cold paths (unmeasured pools, unsafe for unproven speed), routing each flag to its deep skill, and wording feedback as a request for evidence not a change. Fires on "review this for performance", "should I flag this in review", "is this premature optimization". Routes the policy root to go-idiomatic-discipline, should-I to go-perf-methodology.
Guides SIMD / vectorization in Go. The compiler barely autovectorizes, so SIMD means hand-written Plan 9 assembly (//go:noescape stubs, GOARCH .s files, or Avo) as stdlib does for bytes.IndexByte, or the experimental simd/archsimd package (Go 1.26, GOEXPERIMENT=simd, amd64, unstable API). Covers when it pays off — data-parallel hot loops, after algorithm/BCE/SoA — and its costs: assembly bypasses bounds checks and the race detector. Fires on "use SIMD in Go", "vectorize this loop", "AVX in Go", "the simd package". Routes to go-perf-compiler-intrinsics and go-perf-data-oriented-layout.
Guides Go zero-copy I/O and syscall reduction: how io.Copy already lowers to sendfile/splice/copy_file_range on Linux via the ReaderFrom/WriterTo fast path on net.TCPConn and os.File, the concrete-type conditions that keep it (bufio wrapping defeats it), net.Buffers batching writes into one writev(2), and mmap caveats for read-mostly files. Fires on "zero copy in Go", "sendfile", "writev", "mmap a file", "reduce syscalls". Routes buffering to go-perf-buffered-io, unsafe conversion to go-perf-strings-bytes-zerocopy.
What a Go heap allocation costs — the ~70 size classes and rounding waste (unsafe.Sizeof vs real slot), the tiny allocator packing sub-16B pointer-free objects, the lock-free per-P mcache → mcentral → mheap hierarchy, and scannable vs noscan spans (pointer-free objects cut GC cost; "1 alloc/op" hides different costs). Fires on "still slow after removing allocs", "reduce GC pressure", "size class", "how does Go allocate". Routes to go-perf-escape-analysis, go-perf-sync-pool, go-perf-gc-tuning, go-perf-struct-layout.
Guides the atomics-vs-locks performance tradeoff in Go — typed sync/atomic ops (atomic.Int64/Pointer/Bool, 1.19) are a single CAS-style instruction, cheaper than a mutex uncontended but still cache-line-bouncing when contended; sync.Mutex's fast path is itself a CAS that only parks the goroutine when contended; RWMutex wins only for long read sections and is slower (scales worse) than a plain Mutex for short ones; the atomic.Pointer copy-on-write config swap; when lock-free isn't worth the correctness risk. Fires on "atomic vs mutex", "is RWMutex faster", "lock-free counter", "reduce locking overhead", "atomic.Pointer config". Routes copylock/atomic-API correctness to go-sync-primitives, memory ordering to go-race-and-memory-model, measuring to go-perf-block-mutex-profiles.