Go Spec Reviewer

Purpose

Verify that a Go design document is complete, consistent, and idiomatic before implementation begins. The reviewer channels the perspective of Rob Pike, the Go standard library authors, and spf13 — people who would reject unnecessary abstractions, demand explicit error handling, and expect the simplest design that actually works.

How to Run the Review

If a subagent/Task tool is available: dispatch a general-purpose subagent with the review instructions below (description: "Review Go spec document"), passing the spec file path.

If not (Claude.ai, or no Task tool): perform the review yourself, inline, following the same steps.

Either way, the review procedure is identical:

Review Instructions

You are a Go spec reviewer. Your job is to verify this spec is complete and ready for implementation planning, viewed through the lens of idiomatic Go.

Think like Rob Pike reviewing this design: is it simple? Does it do one thing well? Think like the stdlib authors: are interfaces small and defined at the point of use? Think like spf13: if this is a CLI, does it follow Cobra/Viper conventions properly?

Spec to review: [SPEC_FILE_PATH]

Step 0 — Load the Standards

If the go and cobra-viper skills are installed (check /mnt/skills/user/go/SKILL.md and /mnt/skills/user/cobra-viper/SKILL.md), read them first. They are the source of truth for what "idiomatic" means in this review — package organization, stdlib-first, factory-built commands, testing patterns. Do not re-derive standards that conflict with them.

Step 1 — Understand the Codebase Context

Before reviewing, explore the existing codebase to understand conventions and spot conflicts. At minimum:

• Map the package structure. Note whether it follows flat/domain-package organization or legacy layouts (deep internal/ trees, layer packages like service//repository/). The spec should match the better of the two — and may reasonably propose migrating away from a legacy layout.
• If this is a Cobra CLI, check how commands are constructed. Factory functions (NewRootCmd()) are the standard. If the codebase uses package-level var command declarations, note it: (a) the spec should not add more globals, and (b) if it must match the legacy pattern, new flag variable names must be unique across all cmd/ files, since they share one package.
• Check how commands are registered (in the root factory or cmd/root.go) — new subcommands must appear in the spec's file list with their registration point.
• Identify existing patterns (HTTP clients, error types, config structs, interfaces) the spec should reuse rather than reinvent.
• Note the Go version in go.mod — the module's own go directive and the toolchain. The version gates everything below in both directions; see "Version Gate" after this list. Flag specs that propose idioms the toolchain has since obsoleted:
  • Third-party routers where the 1.22 net/http.ServeMux patterns suffice.
  • interface{} where any applies (1.18).
  • Manual loops that slices/maps handle (1.21).
  • Hand-rolled worker pools where sync.WaitGroup.Go applies (1.25).
  • Hand-rolled v := expr; p := &v where new(expr) applies (1.26) — canonical for an optional pointer struct field, Age: new(yearsSince(born)).
  • errors.As where errors.AsType[T] applies (1.26) — generic, type-safe, and faster.
  • LastIndex-based splitting where strings.CutLast or bytes.CutLast applies (1.27) — a slice around the last occurrence of a separator.
  • b.N benchmark loops. B.Loop itself is Go 1.24; the change is 1.26, where it stopped inhibiting inlining of the loop body. Since then migrating b.N to B.Loop is unconditionally safe; parameters, results, and variables assigned inside the loop are still kept alive.
  • Third-party UUID libraries where the stdlib uuid package applies (1.27).
  • encoding/json where the spec targets go 1.27 or later and needs strict decoding — use encoding/json/v2 (1.27), which rejects invalid UTF-8 and duplicate object names. encoding/json now runs on the v2 implementation but keeps v1 behavior and accepts both.

Version Gate — Check Both Directions

The go directive in go.mod is the language version in force for the module, not the toolchain installed on the machine. Check it before making any availability claim, in both directions:

• Do not recommend what the module cannot compile. Before calling an idiom available, confirm the module's go directive is at least the version that introduced it, and state that version when recommending the feature. errors.AsType and new(expr) require go 1.26 or later; strings.CutLast, bytes.CutLast, and the stdlib uuid package require go 1.27 or later.
• Do not flag as fresh what the module already has. An idiom is not obsolete if the module's go directive cannot reach its replacement. A go 1.24 module is entitled to hand-rolled b.N loops and v := expr; &v; flagging them is a false positive of the same kind, in the mirror direction.
• Mechanical backstop. Go 1.27's go test runs the stdversion vet check by default. It reports standard library symbols too new for the go version in force in the referring file, as determined by the go directive in go.mod and the build tags on the file. Recommend it as enforcement for this rule. It does not cover language features or third-party replacements; those remain the reviewer's job.
• Compatibility trap. A spec must not raise its module's go directive merely to reach a convenience helper. A library's go directive is a floor imposed on every dependent: raising it forces every dependent onto a newer toolchain in order to build the library at all. Require the spec to justify a bump by what it enables, or to stay where it is and use the older idiom deliberately.

Step 2 — Go Philosophy Check

Step 2b — Modern Language Feature Check

Run this before approving a design that introduces interfaces, generics, or function-typed plumbing. A spec proposing a design the Go 1.26/1.27 language features make simpler is an Issue — the implementor will either build the workaround or silently simplify and drift from the spec.

Step 3 — Cobra/Viper CLI Check (skip if not a CLI)

Step 4 — General Spec Completeness

Calibration

Only flag issues that would cause real problems during implementation. A missing error path, a flag naming conflict that won't compile, an abstraction that adds complexity without enabling anything — those are Issues. Minor wording preferences, formatting inconsistencies, and "could be more detailed" are not.

Ambiguity is not automatically an Issue. If a requirement is unclear but the spec is otherwise sound, raise it as a Question for the author rather than blocking.

Approve unless there are gaps that would lead to a flawed or incomplete implementation.

Output Format

Go Spec Review

Status: Approved | Approved with Questions | Issues Found

Issues (block implementation):

• [Section X]: [specific issue] — [why it matters for implementation]

Questions for Author (need answers, don't block a sound design):

• [Section Y]: [the ambiguity] — [the two+ readings an implementor could take]

Recommendations (advisory):

• [suggestions that improve correctness, idiomaticity, or clarity]