---
name: go-package-validator
description: "A pass-or-fail validation gate for a Go package before it merges: build, vet, lint, formatting, module tidiness, and test coverage against your threshold, with the exact commands and a CI-ready script. Use when a Go package needs a pre-merge quality gate: build, vet, lint, coverage threshold, and the CI script that enforces them in order. Do not use for diagnosing a specific build failure, or writing the tests themselves. Related topics: coding, package."
---

# Go Package Validator

A pass-or-fail validation gate for a Go package before it merges: build, vet, lint, formatting, module tidiness, and test coverage against your threshold, with the exact commands and a CI-ready script.

## When to use

Use this skill when a Go package needs a pre-merge quality gate: build, vet, lint, coverage threshold, and the CI script that enforces them in order. Do not use it for diagnosing a specific build failure, or writing the tests themselves.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Order the checks from cheapest to most expensive (format and tidy, build, vet, lint, test with race, coverage) so a failure stops the run early.
3. Write the exact command, pass condition, and usual failure reason for every selected check.
4. Add the coverage command that compares the total to the threshold and exits non-zero below it, when coverage is on.
5. List the structural checks tooling misses: package naming, doc comments on exports, init side effects, and correct use of internal.
6. Assemble the gate as a shell script or the CI configuration for the chosen runner and mark each check blocking or advisory.

## Inputs

- **Package import path** (free text, e.g. "github.com/acme/app/pkg/auth")
- **Target Go version** (choose one: 1.21, 1.22, 1.23, 1.24)
- **Verify test coverage** (choose one: Yes, No)
- **Minimum coverage percentage** (number from 0 to 100)
- **Lint tools** (choose any: staticcheck, golangci-lint, go vet, gofmt, ineffassign, govulncheck)
- **Where it runs** (choose one: Local pre-commit, GitHub Actions, GitLab CI, Other CI)
- **Output format** (choose one: Markdown, Plain Text)

## Output

A document in the chosen format with sections Checklist (ordered table of command, pass condition, failure reason), Script (shell or CI YAML), and Notes (blocking versus advisory).

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Go Package Validator

Produce the validation gate my Go package must pass before it merges.

#### Details
- Package import path: {{Package import path}}
- Target Go version: {{Target Go version}}
- Verify test coverage: {{Verify test coverage}}
- Minimum coverage percentage: {{Minimum coverage percentage}}
- Lint tools: {{Lint tools}}
- Where it runs: {{Where it runs}}
- Output format: {{Output format}}

Order the checks from cheapest to most expensive so a failure stops early: gofmt and go mod tidy (the diff must be empty), go build ./..., go vet ./..., the selected linters, then go test with -race, and coverage last. For each check write the exact command, the condition that counts as a pass, and the usual reason it fails. When coverage is on, use go test -coverprofile and a one-line go tool cover or awk command that compares the total to the threshold and exits non-zero below it. Add the structural checks that tools miss: package name matches directory, no exported identifier without a doc comment, no init with side effects, internal used for code that must stay private. Finish with a script (shell, or the CI YAML for the chosen runner) that runs the whole gate in order, and a Notes section that lists which checks are advisory and which are blocking.

## Pitfalls

- Running the expensive test suite before gofmt and go vet, which wastes minutes of CI on a change that a two-second check would reject.
- Checking coverage per file rather than the package total the threshold was set against, which fails on trivial files.
- Leaving linter versions unpinned, so the gate breaks when a new staticcheck release adds rules.
