[
  {
    "id": 1,
    "name": "ask-before-adding-dependency",
    "description": "Tests whether the AI agent asks for user confirmation before adding a new dependency via go get",
    "prompt": "I need to parse YAML configuration files in my Go project. Add the dependency and write the config parsing code.",
    "trap": "Without the skill, the model immediately runs go get for a YAML library without asking the user for confirmation, presenting alternatives, or checking stdlib",
    "assertions": [
      {"id": "1.1", "text": "Asks the user for confirmation before running go get to add a new dependency"},
      {"id": "1.2", "text": "Presents the package name and import path"},
      {"id": "1.3", "text": "Mentions whether the standard library covers the use case (encoding/json does, but YAML does not have stdlib support)"},
      {"id": "1.4", "text": "Lists known alternatives (e.g., gopkg.in/yaml.v3, github.com/goccy/go-yaml)"},
      {"id": "1.5", "text": "Does NOT silently run go get without asking first"}
    ]
  },
  {
    "id": 2,
    "name": "go-sum-must-be-committed",
    "description": "Tests whether the model insists go.sum must be committed to version control",
    "prompt": "I'm setting up a new Go project. My .gitignore currently includes go.sum because it's auto-generated and I don't want to clutter the repo with generated files. Is this okay?",
    "trap": "Without the skill, the model might agree that auto-generated files can be gitignored, missing that go.sum is critical for supply-chain security",
    "assertions": [
      {"id": "2.1", "text": "Strongly advises against gitignoring go.sum"},
      {"id": "2.2", "text": "Explains that go.sum contains cryptographic checksums for dependency verification"},
      {"id": "2.3", "text": "Explains the supply-chain security risk: without go.sum, a compromised proxy could substitute malicious code"},
      {"id": "2.4", "text": "Mentions go mod verify as the mechanism that uses go.sum for integrity checking"},
      {"id": "2.5", "text": "Recommends removing go.sum from .gitignore"}
    ]
  },
  {
    "id": 3,
    "name": "patch-only-upgrade-preference",
    "description": "Tests whether the model prefers go get -u=patch over go get -u for routine updates",
    "prompt": "I want to update all my Go dependencies to the latest versions. What command should I run?",
    "trap": "Without the skill, the model suggests go get -u ./... which upgrades to latest minor/patch, potentially introducing breaking behavioral changes",
    "assertions": [
      {"id": "3.1", "text": "Recommends go get -u=patch ./... as the safer default for routine updates"},
      {"id": "3.2", "text": "Explains that -u=patch only upgrades patch versions which have no API changes per semver"},
      {"id": "3.3", "text": "Explains that -u (without =patch) upgrades minor versions too, which can change behavior"},
      {"id": "3.4", "text": "Mentions running go mod tidy after upgrading"},
      {"id": "3.5", "text": "Does NOT recommend go get -u ./... without warning about the risk of minor version upgrades"}
    ]
  },
  {
    "id": 4,
    "name": "mvs-algorithm-understanding",
    "description": "Tests understanding of Minimal Version Selection — Go selects the minimum satisfying version, not the latest",
    "prompt": "In my Go project, module A requires pkg@v1.2.0 and module B requires pkg@v1.3.0. My go.mod does not mention pkg directly. Which version of pkg will Go select and why?",
    "trap": "Without the skill, the model might say Go selects the latest available version of pkg (like npm/pip would), rather than the minimum required version (v1.3.0)",
    "assertions": [
      {"id": "4.1", "text": "Correctly states that Go selects v1.3.0 (not the latest available version)"},
      {"id": "4.2", "text": "Explains Minimal Version Selection (MVS): Go picks the highest minimum required, not the latest available"},
      {"id": "4.3", "text": "Distinguishes MVS from other package managers (npm, pip, cargo) that select the latest compatible"},
      {"id": "4.4", "text": "Mentions that MVS provides deterministic builds without a lock file"},
      {"id": "4.5", "text": "Explains that go.sum is integrity verification, not version locking"}
    ]
  },
  {
    "id": 5,
    "name": "major-version-suffix-rule",
    "description": "Tests knowledge of Go's major version suffix convention for v2+",
    "prompt": "I'm publishing a Go library and need to release v2.0.0 with breaking changes. What do I need to change in my module path and imports?",
    "trap": "Without the skill, the model might just change the git tag to v2.0.0 without updating the module path to include /v2, breaking the import compatibility rule",
    "assertions": [
      {"id": "5.1", "text": "States that the module path in go.mod must include /v2 suffix (e.g., github.com/example/pkg/v2)"},
      {"id": "5.2", "text": "States that all import paths must be updated to include /v2"},
      {"id": "5.3", "text": "Explains this is Go's import compatibility rule — different major versions are separate modules"},
      {"id": "5.4", "text": "Mentions that v0 and v1 do NOT have a suffix"},
      {"id": "5.5", "text": "Notes that this allows v1 and v2 to coexist in the same build"}
    ]
  },
  {
    "id": 6,
    "name": "replace-directive-library-warning",
    "description": "Tests that the model warns about replace directives being ignored when the module is used as a dependency",
    "prompt": "I'm developing a Go library and I need to use a fork of one of my dependencies for a bug fix. I added a replace directive in my go.mod. Will consumers of my library use the fork too?",
    "trap": "Without the skill, the model might say yes, missing that replace directives only apply in the main module and are ignored when used as a dependency",
    "assertions": [
      {"id": "6.1", "text": "Clearly states that replace directives only take effect in the main module's go.mod"},
      {"id": "6.2", "text": "States that consumers of the library will NOT use the fork — replace is ignored when the module is consumed as a dependency"},
      {"id": "6.3", "text": "Recommends removing replace directives before publishing a library"},
      {"id": "6.4", "text": "Suggests alternative solutions (e.g., upstream the fix, publish the fork as a separate module)"}
    ]
  },
  {
    "id": 7,
    "name": "tool-directives",
    "description": "Tests whether the model knows Go 1.24+ tool directives for pinning CLI tool versions in go.mod",
    "prompt": "My Go project uses golangci-lint and govulncheck. I want to ensure all developers and CI use the exact same versions of these tools. How do I pin them?",
    "trap": "Without the skill, the model suggests go install @latest in CI, a Makefile, or the old tools.go blank-import workaround, missing Go 1.24+ tool directives that pin versions via go.mod",
    "assertions": [
      {"id": "7.1", "text": "Recommends Go 1.24+ go.mod tool directives"},
      {"id": "7.2", "text": "Uses go get -tool to add golangci-lint and govulncheck"},
      {"id": "7.3", "text": "Uses go tool to run the pinned tools reproducibly"},
      {"id": "7.4", "text": "Mentions running go mod tidy and reviewing go.mod/go.sum after adding tools"},
      {"id": "7.5", "text": "Does NOT create a new tools.go blank-import file unless the module targets Go <1.24"}
    ]
  },
  {
    "id": 8,
    "name": "govulncheck-call-path-analysis",
    "description": "Tests understanding that govulncheck does static analysis to find actually-called vulnerable functions, not just dependency presence",
    "prompt": "My Go project has a dependency flagged by a CVE scanner. But I only use a small subset of the library's API. Is there a way to check if the vulnerability actually affects my code?",
    "trap": "Without the skill, the model suggests just upgrading the dependency or manually reviewing the CVE, missing govulncheck's call-path analysis that filters by actual usage",
    "assertions": [
      {"id": "8.1", "text": "Recommends govulncheck as the tool to check if the vulnerability is actually reachable from your code"},
      {"id": "8.2", "text": "Explains that govulncheck uses static analysis to trace call paths to vulnerable functions"},
      {"id": "8.3", "text": "Explains that if your code never calls the affected function, govulncheck will NOT flag it"},
      {"id": "8.4", "text": "Shows the govulncheck ./... command"},
      {"id": "8.5", "text": "Distinguishes govulncheck from generic CVE scanners that flag any dependency presence regardless of usage"}
    ]
  },
  {
    "id": 9,
    "name": "go-work-sum-gitignore",
    "description": "Tests that go.work.sum should not be committed while go.sum should be committed",
    "prompt": "I'm setting up a Go workspace with go.work for local multi-module development. Which workspace files should I commit to git?",
    "trap": "Without the skill, the model might treat go.work.sum the same as go.sum (commit both), but go.work.sum should NOT be committed",
    "assertions": [
      {"id": "9.1", "text": "States that go.work.sum should NOT be committed to version control"},
      {"id": "9.2", "text": "Recommends adding go.work.sum to .gitignore"},
      {"id": "9.3", "text": "Explains that go.work is for development only and does not affect published module consumers"},
      {"id": "9.4", "text": "Distinguishes this from go.sum which MUST be committed"},
      {"id": "9.5", "text": "May mention that go.work itself can optionally be committed depending on team preference"}
    ]
  },
  {
    "id": 10,
    "name": "exclude-vs-retract-distinction",
    "description": "Tests understanding of the difference between exclude (consumer-side) and retract (author-side) directives",
    "prompt": "I published a Go library version v1.3.0 that has a critical bug. How do I prevent users from downloading it? Also, one of my dependencies has a buggy version — how do I skip it in my project?",
    "trap": "Without the skill, the model conflates exclude and retract, or uses them interchangeably",
    "assertions": [
      {"id": "10.1", "text": "Uses retract for the published library (author-side: marks own version as broken)"},
      {"id": "10.2", "text": "Uses exclude for the buggy dependency (consumer-side: skips a specific version of someone else's module)"},
      {"id": "10.3", "text": "Explains that retract goes in the library's own go.mod and warns users via go list"},
      {"id": "10.4", "text": "Explains that exclude redirects to the next higher available version"},
      {"id": "10.5", "text": "Notes that retracted versions are still downloadable but not selected by default"}
    ]
  },
  {
    "id": 11,
    "name": "test-dependency-upgrade-flag",
    "description": "Tests knowledge of the -t flag for including test dependencies in upgrades",
    "prompt": "I ran go get -u ./... to upgrade my Go dependencies, but my test dependencies (like testify) weren't upgraded. Why?",
    "trap": "Without the skill, the model doesn't know about the -t flag and suggests upgrading test deps individually",
    "assertions": [
      {"id": "11.1", "text": "Explains that go get -u ./... excludes test-only dependencies by default"},
      {"id": "11.2", "text": "Recommends go get -u -t ./... to include test dependencies in the upgrade"},
      {"id": "11.3", "text": "Explains the difference between -u (production deps) and -u -t (production + test deps)"}
    ]
  }
]

# Auditing Dependencies

## Test-Only vs Binary Dependencies

Go's `go.mod` does **not** distinguish between test-only and production dependencies. All modules appear together, with `// indirect` marking transitive dependencies.

### What Gets Included in Your Binary

- `*_test.go` files are **never** compiled by `go build` — only by `go test`
- Packages imported only by test files are not linked into the final binary
- However, their modules still appear in `go.mod`

### Module Graph Pruning (Go 1.17+)

With `go 1.17` or higher in `go.mod`, Go prunes the module graph: transitive dependencies needed only for tests of other modules are excluded from the build graph. This reduces `go.mod` size and avoids downloading unnecessary modules.

### Upgrading With or Without Test Dependencies

```bash
go get -u ./...       # Upgrade deps, EXCLUDING test-only deps
go get -u -t ./...    # Upgrade deps, INCLUDING test-only deps
```

### Impact on Binary Size

To check whether a large dependency is actually linked into your binary (vs. only used in tests), use `goweight` or `go-size-analyzer` — if the package doesn't appear in the binary breakdown, it's test-only and not contributing to binary size.

## Vulnerability Scanning with govulncheck

`govulncheck` reports known vulnerabilities that affect your code. It uses static analysis to narrow reports to vulnerabilities in code paths your project actually calls — unlike generic CVE scanners that flag every dependency regardless of usage.

```bash
# Scan source code (most common)
govulncheck ./...
# Or, when govulncheck is pinned with a Go 1.24+ tool directive:
go tool govulncheck ./...

# Scan a compiled binary
govulncheck -mode=binary ./bin/myapp

# JSON output (for CI integration)
govulncheck -format json ./...

# Include test code in analysis
govulncheck -test ./...
```

Output shows the vulnerability ID, affected module, fixed version, and the call trace from your code to the vulnerable function. If a vulnerability exists in a dependency but your code never calls the affected function, `govulncheck` does not flag it.

For CI pipeline integration, see the `samber/cc-skills-golang@golang-continuous-integration` skill.

## Tracking Outdated Dependencies with go-mod-outdated

`psampaz/go-mod-outdated` lists outdated direct dependencies with available updates.

```bash
# Show outdated direct dependencies with available updates
go list -u -m -json all | go-mod-outdated -update -direct

# Fail in CI if dependencies are outdated
go list -u -m -json all | go-mod-outdated -update -direct -ci

# Markdown output
go list -u -m -json all | go-mod-outdated -update -direct -style markdown
```

Output columns: MODULE, CURRENT version, WANTED (latest minor/patch), LATEST (latest overall), and VALID TIMESTAMPS (warns if an "update" is chronologically older than current).

## Analyzing Dependency Size with goweight

`jondot/goweight` lists every package linked into the binary sorted by size contribution. It helps identify bloated dependencies and evaluate whether a lighter alternative exists.

```bash
goweight          # Sort by size
goweight --json   # JSON output for CI tracking
```

**Modern alternative**: [go-size-analyzer](https://github.com/Zxilly/go-size-analyzer) (`gsa`) supports ELF, Mach-O, PE, and WebAssembly formats with interactive HTML/SVG visualization:

```bash
go get -tool github.com/Zxilly/go-size-analyzer/cmd/gsa@latest
go build -o ./myapp ./cmd/myapp
go tool gsa -f html -o size-report.html ./myapp
```

# Automated Dependency Updates

Automate minor/patch dependency updates to reduce maintenance burden and stay current with security fixes. This requires a solid CI pipeline — tests and linting must pass before any auto-merge.

## Dependabot vs Renovate

| Feature | Dependabot | Renovate |
| --- | --- | --- |
| Platform | GitHub only | GitHub, GitLab, Bitbucket, self-hosted |
| `go mod tidy` | Automatic | Opt-in (`gomodTidy`) |
| Automerge | Separate workflow | Native support |
| Grouping | Pattern-based | More flexible rules |
| Monorepo support | Basic | Go workspaces aware |
| Regex managers | No | Yes (Dockerfiles, Makefiles, etc) |

**Renovate is generally more mature and configurable.** Dependabot is simpler to set up for GitHub-only projects.

## Auto-Merge Strategy

- **Minor and patch updates**: Auto-merge only after CI passes (tests + lint + govulncheck) and the package is low-risk for the project
- **Major updates**: Create PR for manual review (may contain breaking changes)
- **Security updates**: Auto-merge regardless of version bump type

For workflow configuration files (dependabot.yml, renovate.json, auto-merge workflows), see the `samber/cc-skills-golang@golang-continuous-integration` skill.

## Update Verification

Before committing a dependency update:

0. Changelogs may suggest improvements applicable to the project.
1. Run `go test ./...` and `go build ./...`
2. Scan with `govulncheck ./...` or `go tool govulncheck ./...`
3. Release notes/changelogs for libraries that affect persistence, serialization, networking, authentication, authorization, cryptography, or public APIs may contain important information about breaking changes
4. Major version upgrades may contain breaking changes — the package's changelog documents them
5. New APIs or patterns introduced in the updated version may offer improvements worth considering

# Dependency Conflicts & Resolution

## Diagnosing Conflicts

```bash
# See why a module is in your build
go mod why -m github.com/some/module

# See which version is selected
go list -m github.com/some/module

# See the full requirement graph
go mod graph

# List all modules in the build
go list -m all
```

## Resolution Strategies

**Force a specific version** (when two deps require incompatible versions):

```bash
go mod edit -replace=example.com/pkg@v1.2.0=example.com/pkg@v1.3.1
```

```go
// go.mod
replace example.com/pkg v1.2.0 => example.com/pkg v1.3.1
```

**Use a local fork** (for debugging or patching):

```go
replace example.com/pkg => ../my-local-fork
```

**Block a problematic version**:

```bash
go mod edit -exclude=example.com/pkg@v1.3.0
```

When a version is excluded, any requirement on that version is redirected to the next higher available version.

**Force upgrade a transitive dependency**:

```bash
go get github.com/transitive/dep@v1.5.0
```

This adds an explicit requirement in your `go.mod`, overriding whatever the transitive dependency chain would select via MVS.

## Resolution Workflow

1. Run `go mod graph` and `go mod why -m <module>` to understand the dependency chain
2. Identify which of your direct dependencies pulls in the conflicting version
3. Try upgrading the direct dependency first: `go get github.com/direct/dep@latest`
4. If that doesn't resolve it, use `replace` or `exclude` as a temporary fix
5. Run `go mod tidy` to clean up
6. Verify with `go build ./...` and `go test ./...`

**Important**: `replace` and `exclude` directives only take effect in the **main module's** `go.mod`. They are ignored when your module is used as a dependency. Remove `replace` directives before publishing a library.

## Retract (For Module Authors)

Mark versions as broken or accidentally published:

```go
// go.mod
retract v1.0.0         // Contains critical bug in auth
retract [v1.1.0, v1.2.0] // Range of broken versions
```

Retracted versions are still downloadable but `go get` will not select them by default, and `go list -m -u` warns about them.

# Versioning & Minimal Version Selection

## Semantic Versioning (SemVer)

Go modules use **`vMAJOR.MINOR.PATCH`** (the `v` prefix is required):

- **MAJOR**: Breaking changes to the public API
- **MINOR**: Backward-compatible new functionality
- **PATCH**: Backward-compatible bug fixes

### Stability Rules

| Version     | Stability                                 |
| ----------- | ----------------------------------------- |
| `v0.x.x`    | Unstable — no compatibility guarantees    |
| `v1.x.x`+   | Stable — backward-compatible within major |
| Pre-release | Unstable (e.g., `v1.5.0-beta.1`)          |

### Major Version Suffix Rule

For `v2` and above, the module path must include a `/vN` suffix. This is Go's import compatibility rule — different major versions are treated as entirely separate modules, allowing them to coexist in the same build:

```go
// go.mod
module github.com/example/pkg/v2

// Import in code
import "github.com/example/pkg/v2/subpkg"
```

Tags: `v2.0.0`, `v2.1.0`, etc. The `v0` and `v1` versions have no suffix.

### Special Cases

- **Pseudo-versions**: For untagged commits — `v0.0.0-20210101120000-abcdef123456` (base version + timestamp + commit hash)
- **`+incompatible`**: Marks `v2+` modules that have not adopted the `/vN` path convention
- **`gopkg.in`**: Always uses a version suffix with a dot — `gopkg.in/yaml.v3`

## Minimal Version Selection (MVS)

Go's dependency resolution algorithm is fundamentally different from npm, pip, or cargo.

### How It Works

Most package managers select the **latest** compatible version of each dependency. Go does the opposite: it selects the **minimum version that satisfies all requirements**. If module A requires `pkg@v1.2.0` and module B requires `pkg@v1.3.0`, MVS selects `v1.3.0` — the highest minimum required, not the latest available.

### Why This Design

- **Deterministic without a lock file**: Given the same `go.mod` inputs, MVS always produces the same build list. `go.sum` is just integrity verification.
- **High fidelity**: Builds closely match what module authors tested against, since the nearest compatible version is selected rather than the latest.
- **No solver needed**: The algorithm is simple graph traversal (under 50 lines of code), not an NP-hard constraint satisfaction problem.
- **Reproducible across machines**: No "works on my machine" from different lock file states.

### Upgrades and Downgrades

- **Upgrade**: `go get pkg@v1.5.0` adds an edge to `v1.5.0` in the module graph and reruns MVS. Only the minimum necessary changes propagate.
- **Downgrade**: `go get pkg@v1.2.0` removes all versions above `v1.2.0` from the graph, then walks backward to find the latest remaining versions of affected dependencies.

# Visualizing the Dependency Graph

## go mod graph (Built-in)

```bash
go mod graph
```

Output: each line contains two space-separated fields (module and its requirement) in `path@version` format:

```
example.com/main github.com/google/uuid@v1.6.0
example.com/main golang.org/x/text@v0.3.7
github.com/google/uuid@v1.6.0 golang.org/x/sys@v0.0.0-20210615035016
```

## go mod why

```bash
go mod why -m github.com/some/module
```

Shows the shortest import path from your code to the module — useful for understanding why an unexpected dependency exists.

## Generate a Graph Image with modgraphviz

Pin `modgraphviz` as a module tool, then pipe `go mod graph` into it.

```bash
go get -tool golang.org/x/exp/cmd/modgraphviz@latest
go mod graph | go tool modgraphviz | dot -Tpng -o deps.png
```

Green nodes represent versions selected by MVS (in the final build list). Grey nodes are versions that exist in the requirement graph but are not used.

## Interactive Visualization with go-mod-graph

`go-mod-graph` (samber/go-mod-graph) is a web-based interactive dependency explorer with zoomable graph, module weight indicators, searchable module list, and MVS algorithm visualization.

## Complementary Analysis

Pin `digraph` as a module tool for graph queries.

```bash
go get -tool golang.org/x/tools/cmd/digraph@latest
# General graph queries on go mod graph output
go mod graph | go tool digraph reverse example.com/some/module
```

# Go Workspaces (go.work)

## go.work vs go.mod

| Scenario                                       | Use       |
| ---------------------------------------------- | --------- |
| Single module project                          | `go.mod`  |
| Developing multiple related local modules      | `go.work` |
| Monorepo with separate Go modules              | `go.work` |
| Testing local changes across module boundaries | `go.work` |
| Published library consumed by others           | `go.mod`  |

## Workspace Commands

```bash
go work init                    # Initialize workspace
go work use ./services/auth     # Add module to workspace
go work use -rm ./old-module    # Remove module from workspace
go work sync                    # Sync workspace with module changes
```

## Key Points

- Workspaces eliminate the need for `replace` directives during local development — the workspace automatically resolves local modules
- **Do not commit `go.work.sum`** to version control (add to `.gitignore`)
- `go.work` is for development only — it does not affect how consumers of your published modules resolve dependencies
- For workspace directory structure examples, see the `samber/cc-skills-golang@golang-project-layout` skill