go-spec-reviewer

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 v1 defaults where the spec targets go 1.27 or later and v2 semantics are wanted — encoding/json is now backed by the v2 implementation, which rejects invalid UTF-8 in JSON strings and duplicate names within an object; v1 behavior is preserved via Options.