Skip to content

ValentinNikolaev/agent-skills / agent-plugins/skills/code-review

code-review

Verified

Review local or PR diffs for defects, including UI/UX and accessibility failures, and test gaps without edits. Route standalone plans, specs, and feedback elsewhere.

references/review-go.md

View on GitHub
# Go Review Checks

Apply these checks only to changed Go behavior and nearby tests. The repository's `AGENTS.md`, `go.mod`, Go version, and established error and test conventions take precedence. Report a finding only after tracing a concrete failure path through the changed code.

## Production code

- Trace pointer and interface values from creation to use. A nil guard on one access does not protect a later dereference; distinguish a nil interface from an interface holding a typed nil when relevant.
- Follow errors through the caller boundary. Check whether errors are dropped, mislabeled, wrapped in a way that loses required identity, or converted into apparent success. When a changed function starts returning or changes an error/status, check that every branch's return reflects its outcome: a handled sentinel on a failure branch makes callers treat failed work as complete. Use `errors.Is` and `errors.As` only where the project exposes matching or typed-error contracts.
- For goroutines, identify the owner, exit condition, context cancellation, waits, and what happens when a caller returns early. For channels, identify who sends, receives, and closes; do not propose closing from a non-owner merely to quiet a leak.
- For shared state, inspect all relevant accesses and synchronization, including tests. A passing non-race test does not establish race freedom.
- On changed interfaces or method signatures, search implementations, callers, registrations, mocks, and generated interfaces before declaring them updated or broken.
- Check map lookups that purport to prove membership: the zero value alone is insufficient when the `ok` result matters.
- Follow slice backing arrays and map references across copies, returned values, caches, and goroutine boundaries. An `append` can mutate storage still observed elsewhere; a copied slice header is not an independent buffer. Report aliasing only when the shared mutation affects a reachable contract.
- Trace resource ownership on success, early return, and partial failure. Check deferred argument evaluation, defers accumulating inside long loops, response-body closure, and database rows' final iteration error where those paths changed.

## Contracts and alternate execution paths

- Check behavioral promises in changed doc-comments against the implementation and delegated operations. Ownership, concurrent use, repeated calls, errors, and side effects are caller-visible contracts. Cite the promise and the contradicting path together; do not infer a defect from missing locks or a comment's wording alone.
- When two implementations of an operation must preserve the same result, compare them using equivalent inputs and state. Inspect cache hits/misses, retries, and buffered/direct execution for lost fields, different error outcomes, and duplicated or omitted effects. Respect intentional differences such as documented freshness or delivery guarantees.
- Follow a callback from registration to its actual invocation sites. Establish whether it is called at all, retried, reused, or invoked concurrently, then check captured state and effects against that lifecycle. Registration alone proves neither execution nor a single invocation.
- For explicit numeric conversions, establish the reachable input range, destination width/sign, supported architectures, and rounding requirements. Report narrowing, sign changes, or truncation only when an allowed input produces a wrong value; an existing range check can make the conversion sound.
- Check whether a result depends on the traversal order of a map. When selection, output, or precedence must be stable, require the code to establish that order or an order-independent reduction. Do not flag order-insensitive aggregation, or claim an observed failure from a random run that happened to pass.

## Cancellation and bounded work

- Follow the incoming context through HTTP, database, retry, and goroutine boundaries. Check that cancel functions are called or ownership is explicitly transferred. A fresh `Background` or `WithoutCancel` needs a justified lifetime, shutdown owner, and bound; detaching cancellation does not create those guarantees.
- For each promised timeout, name the call it must bound and verify that the actual operation observes cancellation, including connection acquisition, transaction/lock waits, and cleanup. Passing a context to a wrapper does not bind a context-free transaction or client beneath it. A deadline checked only after a blocking call returns bounds nothing; budget arithmetic is incomplete while any step can block indefinitely. Test with that operation held pending, not just a slow but returning call.
- Identify both the number of active workers and the amount of queued work under untrusted or large input. `WaitGroup.Go` handles bookkeeping, not a concurrency limit or error propagation. Use it only on a supported Go version; do not reject a justified worker pool or mutex because another idiom exists.
- For channels, trace cancellation while blocked on either send or receive. Check who observes worker errors and who drains or stops work after the first failure. A buffer alone does not establish a shutdown path.

## Database and production boundaries

- Follow a transaction through every return and check which operations actually use the transaction rather than the outer pool. Check commit errors, rollback handling, cancellation, and the isolation/locking contract relevant to the changed operation.
- Check query parameters and driver-specific placeholders rather than assuming one SQL dialect. Trace tenant or authorization scope from trusted identity to the actual query. Do not flag safe SQL fragments solely because concatenation occurs.
- For changed HTTP services, inspect request/body limits, configured timeouts, streaming behavior, and graceful shutdown against the real deployment. Avoid imposing arbitrary timeout values or a blanket ban on wildcard bind addresses.
- For telemetry, inspect context propagation, goroutine ownership, and shutdown/flush behavior. Check metric units and cardinality; do not put raw user input, credentials, or unbounded identifiers into labels or logs.

## Tests

- Read the package's test runner and existing conventions before judging table-driven tests, subtests, fixtures, or test doubles. Do not require a table for a single meaningful case.
- Check that each case asserts the behavior it names, including the error path and a discriminating observable. For bug fixes, identify whether the assertion would fail before the fix; use the main skill's proportional negative-control rule.
- Do not demand `t.Parallel` by default. When it is used, check for shared fixtures, mutable globals, and process-wide changes. `t.Setenv` and `t.Chdir` cannot run in a parallel test or below a parallel ancestor.
- Keep `t.Fatal` and `t.FailNow` in the test goroutine. For HTTP handlers or background goroutines, return an error through a channel or another observable the test can assert.
- For HTTP adapter tests, inspect the request actually sent and the response/error contract. `httptest` may test the boundary without calling a live service; label skipped integration work as unrun, not passed.
- When a test claims all registry entries or cases are covered, verify membership and counts instead of accepting zero values or vacuous loops.
- Prefer deterministic coordination for concurrent tests; arbitrary sleeps and a green race-detector run do not prove that the contested order occurred. Consider `testing/synctest` only when the project's Go version supports it and its model fits the code.
- Do not require or forbid testify, leak detectors, table-driven tests, or mocks as a universal rule. Apply the project's existing conventions and judge whether the assertion distinguishes the intended behavior.

## Dependency changes and Dependabot

When any `go.mod` or `go.sum` changes, reconcile repository alerts with the reviewed PR head, even if no Go source changed or `govulncheck` is clean. Resolve the repository from the PR's base repository, not the contributor's fork. Fetch all pages read-only, quoting the query string:

```text
gh api --method GET --paginate 'repos/<owner>/<repo>/dependabot/alerts?state=open&per_page=100'
```

Use the verified host for GitHub Enterprise. Record the repository, retrieval time, reviewed base/head, and whether pagination completed. Authentication/permission errors, unavailable or disabled alerts, and incomplete pagination are verification limits, not an empty alert list. Do not request write permission, enable Dependabot, dismiss alerts, or update their state as part of review. See the [GitHub alert API](https://docs.github.com/en/rest/dependabot/alerts#list-dependabot-alerts-for-a-repository).

For each Go alert, match `dependency.package.name` and `dependency.manifest_path` to the effective selected module version at the PR head, including indirect dependencies, workspace selection, and `replace` directives. Compare against the advisory's `vulnerable_version_range` and applicable patched release line; a version bump alone is not a fix. A `go.sum` entry can be historical or contain multiple versions and does not prove which version is selected. Resolve uncertain selection using read-only evidence or the scratch isolation below, or mark it unresolved. Check the specific manifest: fixing the same module in one directory does not fix another directory's alert.

Account for every returned open alert in dependency-alert evidence. Use `covered by PR` only when base/head evidence demonstrates that this PR upgrades a vulnerable version to a safe one or removes the dependency from the affected manifest's selected graph. Mark a known vulnerable head version as `still affected`, an out-of-scope dependency as `not addressed`, and missing selection or advisory evidence as `unresolved`. Use `unaffected at head` for an already-safe/stale alert without demonstrated PR remediation. Preserve alerts for unchanged modules, other manifests, and other ecosystems as existing/out-of-scope inventory rather than silently dropping them, recording unchanged status separately from exposure. These are predictions at the reviewed head, not claims that GitHub has closed the alerts.

List every alert not demonstrated covered, uncapped by `--max-findings`, in verification evidence or the caller-requested report; compact output must retain the inventory or point to that complete report. Include alert number/link, GHSA/CVE, severity, ecosystem/module, manifest, selected head version (or unknown), vulnerable range, patched version (or none published), and reconciliation status/reason. Separate unchanged security debt from defects introduced or left incomplete by this PR; only promote a row to Findings under the main skill's causal-scope, evidence, and severity rules.

For Go alerts, also record Go Vulnerability Database coverage as `GO-ID found`, `no matching entry found`, or `not checked/unavailable`. Correlate the module and GHSA/CVE aliases against current [Go vuln DB records](https://go.dev/doc/security/vuln/database), recording lookup source/time; absence of a GO-ID in the GitHub payload or a clean `govulncheck` run alone does not establish absence from the database. Highlight alerts with no matching Go DB entry and retain their GitHub advisory/version evidence. Unknown or absent Go DB coverage never clears a Dependabot alert. Keep module-version exposure separate from symbol reachability and do not claim a repository-wide security clearance from either source.

## Verification

Keep dependency checks read-only. Use `go mod tidy -diff` when the installed toolchain supports it; a nonzero exit with a dependency diff means changes are needed, not that they were applied. Otherwise copy the module's `go.mod` to `<scratch>/review.mod` and its existing `go.sum`, if present, to `<scratch>/review.sum`, outside the checkout, and pass `-modfile=<scratch>/review.mod` to the check. Go derives the alternate checksum path from the `.mod` filename. Use `GOWORK=off` for this single-module check; if workspace behavior is essential, use an isolated scratch copy that preserves it or report that verification limit. Keep caches and other outputs outside the checkout too. `-mod=readonly` alone does not guarantee an unchanged `go.sum`. Never fall back to plain `go mod tidy`, `go get`, or `-mod=mod` using the checkout's module files. See the [Go module command flags](https://go.dev/ref/mod#build-commands) and [`go mod tidy -diff`](https://go.dev/ref/mod#go-mod-tidy).

Prefer the repository's narrow package test command. Suggest a targeted race-detector run when changed concurrency creates a plausible race and the environment supports it; it has substantial runtime cost and only observes paths executed by the test. Do not infer race freedom from one green run.

Inspect `go.mod`, `go.work`, build tags, generated files, and the toolchain actually used before recommending newer APIs. Keep a whole-system security audit in `go-security-audit` and reproducible performance measurement in `go-benchmark`; neither runs automatically as part of this diff review. A style modernization or generic optimization claim is not a defect without a concrete failure or measured contract violation.

Selected lifecycle, context, safety, database, testing, and telemetry checks are adapted from [Samber's Go skills](https://github.com/samber/cc-skills-golang/tree/8e899e20ff0cd4dc524af3993e4c62d8ee8c5717/skills); version-aware API and bounded-concurrency guidance also adapts [spf13's Go skill](https://github.com/spf13/go-skills/blob/9ac6eca43161163bb21621a520a57df50d5ad464/go/SKILL.md). See the package's scoped MIT licenses and repository third-party notices.

Go references: [testing package](https://pkg.go.dev/testing), [race detector](https://go.dev/doc/articles/race_detector), [numeric conversions](https://go.dev/ref/spec#Conversions), [map iteration](https://go.dev/ref/spec#For_statements).
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall