go-spec-reviewer

name

go-spec-reviewer

description

Review design specification documents for Go programs before implementation begins. Use this skill when a user has a Go spec to review, wants feedback on a design doc, is about to start implementing from a spec, asks "is this spec ready?", or wants a technical review of a planned feature in a Go codebase. Applies Go philosophy — simplicity, composition, explicit errors, context propagation — plus Cobra/Viper CLI conventions where applicable.

Go Spec Reviewer

Purpose

Dispatch a spec reviewer subagent to 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.

---

Dispatch Template

Task tool (general-purpose):
  description: "Review Go spec document"
  prompt: |
    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 1 — Understand the Codebase Context

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

    - List existing packages under `internal/` and `cmd/` to understand structure
    - If this is a Cobra CLI, scan `cmd/` for existing package-level `var` declarations
      to detect flag naming conflicts (all cmd files share one package)
    - Check `cmd/root.go` for how commands are registered
    - Identify any existing patterns (HTTP clients, error types, interfaces) the spec
      should reuse rather than reinvent

    ## Step 2 — Go Philosophy Check

    | Concern | What to Look For |
    |---------|-----------------|
    | Simplicity | Unnecessary layers, abstractions with only one implementation, over-engineered designs |
    | Interfaces | Defined by the consumer, not the implementor? Small (1–3 methods)? Used where polymorphism is actually needed? |
    | Error handling | Errors returned explicitly? Properly wrapped with `fmt.Errorf("%w", err)`? Not swallowed silently? |
    | Context | `context.Context` threaded through any I/O, HTTP, or long-running calls? Timeouts specified? |
    | Concurrency | Goroutines with clear ownership? Channels or mutexes used correctly? Data races avoided? |
    | Package design | Each package has a single clear responsibility? New packages justified vs. extending existing ones? |
    | Naming | Short, clear names following Go conventions? No stutter (`pkg.PkgThing`)? |
    | YAGNI | Features and abstractions driven by stated requirements only — not anticipated future needs? |

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

    | Concern | What to Look For |
    |---------|-----------------|
    | Flag naming | Package-level flag vars in `cmd/` must be unique across all command files — they share one package. Prefer command-scoped names (e.g. `servePort`, not `port`) |
    | Command registration | New subcommands must be registered in `cmd/root.go` via `rootCmd.AddCommand(...)` — is this in the spec's file list? |
    | RunE vs Run | Prefer `RunE` so errors propagate; `Run` silently swallows them |
    | Persistent vs local flags | Config-level flags belong on the root command as persistent; operation-specific flags belong on the subcommand |
    | Viper binding | If Viper is used, are env var names and config keys explicitly bound? Are defaults set? |
    | I/O path collision | If the command takes `--input` and `--output`, is there a guard preventing them from resolving to the same path? |

    ## Step 4 — General Spec Completeness

    | Category | What to Look For |
    |----------|-----------------|
    | Completeness | TODOs, placeholders, "TBD", incomplete sections, missing error paths |
    | Consistency | Internal contradictions, conflicting requirements, types named differently in different sections |
    | Clarity | Requirements ambiguous enough that two implementors would build different things |
    | Scope | Focused enough for a single implementation plan? Not covering multiple independent subsystems? |
    | Data flow | Clear what enters and exits each function or step? |
    | Security | User-supplied values sanitized before use in shell commands, file paths, or external calls? |

    ## 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.

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

    ## Output Format

    ## Go Spec Review

    **Status:** Approved | Issues Found

    **Issues (if any):**
    - [Section X]: [specific issue] — [why it matters for implementation]

    **Recommendations (advisory, do not block approval):**
    - [suggestions that improve correctness, idiomaticity, or clarity]

Reviewer returns: Status, Issues (if any), Recommendations