// Audit Go nolint directives for staleness and lazy justifications. Mechanically verifies each suppression with golangci-lint, then runs adversarial Red/Blue/White debates on the top candidates for removal. Use when inheriting a Go codebase, during periodic cleanup, or when nolint count is growing unchecked.
Use when creating or updating AGENTS.md files, .github/copilot-instructions.md, or other AI agent rule files, onboarding AI agents to a project, standardizing agent documentation, or when anyone mentions AGENTS.md, agent rules, project onboarding, or codebase documentation for AI agents.
Prepares Go applications to work effectively with AI coding agents. Use when setting up a new Go project or retrofitting an existing one to ensure: structured JSON logging (slog/Zap/ZeroLog/Logrus), machine-readable command output, thorough golangci-lint configuration, non-interactive CLI design with --yes flags, structured error handling with meaningful exit codes, proper context.Context propagation, graceful shutdown, health check endpoints, and a standardized Makefile. Triggers when a user asks to make their Go app "agent-ready," "AI-friendly," wants to improve agent tooling/observability in a Go project, or needs to audit an existing Go project against agent-readiness best practices.
Validate commit messages against the Conventional Commits specification. Auto-detects and installs commitlint CLI if missing. Checks project config or falls back to sensible defaults. Use when validating commit messages, preparing PRs, or enforcing commit conventions.
Validate markdown files against formatting standards. Auto-detects and installs markdownlint-cli if missing. Checks project config or falls back to sensible defaults. Supports auto-fix mode. Use when creating or modifying markdown files, validating documentation, or enforcing markdown conventions.
Generate a PR_MESSAGE.md file from session context using GitHub CLI. Detects related issues via branch-keyword search, writes a structured PR description with commit subject, summary, test plan, and changelog. Validates with commitlint and markdownlint. Use when preparing a pull request on GitHub.
Strategic roadmap management for GitHub repositories. Syncs ROADMAP.md with GitHub Issues and labels, bootstraps roadmap files from scratch, runs brainstorming sessions with boundary checking, and provides quick status summaries. Use when managing project planning, syncing roadmap state, or exploring feature ideas.
| name | go-nolint-audit |
| description | Audit Go nolint directives for staleness and lazy justifications. Mechanically verifies each suppression with golangci-lint, then runs adversarial Red/Blue/White debates on the top candidates for removal. Use when inheriting a Go codebase, during periodic cleanup, or when nolint count is growing unchecked. |
| compatibility | Requires Go and golangci-lint. Only applicable to Go projects with //nolint directives. |
Audit //nolint: directives in Go codebases. Finds suppressions that
are stale (code changed, lint rule no longer triggers) or lazily
justified (the underlying code could be fixed instead of suppressed).
Challenges each justification through adversarial debate rather than
accepting comments at face value.
go version 2>/dev/null && golangci-lint --version 2>/dev/null
If go is not installed, stop and report. If golangci-lint is
missing:
Do not proceed without both tools available.
grep -rn '//nolint' --include='*.go' . | grep -v vendor/
Match all variants: //nolint (bare), //nolint:rule,
//nolint:rule1,rule2. For each directive, capture:
//nolint:rule // if present)Bare //nolint (no rule) suppresses everything — flag for Phase 2
automatically. If zero directives found, report a clean codebase
and stop.
For each directive with a named rule, test whether the suppression
is still needed. Co-enable nolintlint alongside the target rule:
# v2 syntax (preferred):
golangci-lint run --enable-only=<rule>,nolintlint \
--allow-parallel-runners <file>
# v1 syntax (if v2 unavailable):
golangci-lint run --disable-all --enable=<rule>,nolintlint \
--allow-parallel-runners <file>
If nolintlint reports the directive as unused, it is stale. This
avoids modifying source files. For multi-rule directives
(//nolint:rule1,rule2), test each rule separately. Run up to 3
parallel shell commands. Always use --allow-parallel-runners.
If golangci-lint fails for reasons other than the target rule (build errors, missing deps), skip the directive and report as "unable to verify."
Categorize each directive:
Report stale directives immediately. If all are stale, skip Phase 2.
Bare //nolint directives skip Phase 1 — they cannot be verified
against a specific rule.
Score all discovered directives (not just the Phase 1 sample) on two dimensions (1-5). For large codebases (50+ directives), sample 5-10 across different rules for Phase 1, but score the full list here to find the worst offenders:
Score = Fixability x Justification quality. Consult
references/go-nolint-patterns.md for scoring guidance.
Debate the top 3 by score:
Stale (safe to remove):
file.go:42 //nolint:errcheck — rule no longer triggers
file.go:87 //nolint:mnd — rule no longer triggers
Unable to verify:
file.go:99 //nolint:gosec — golangci-lint build error
For each debated directive:
#N: file.go:line — //nolint:rule
Current code (with nolint): [5-10 lines of surrounding code]
Justification: "original comment" Lint warning when removed: [exact golangci-lint output]
Red (remove): [argument + concrete diff] Blue (keep): [argument with specific reasoning] White (verdict): REMOVE | KEEP | REWRITE JUSTIFICATION [reasoning]
[If REMOVE: repeat diff for easy application] [If REWRITE: full replacement line with improved justification]
| # | File:Line | Rule | Verdict | Effort |
|---|---|---|---|---|
| 1 | location | rule | verdict | effort |
| 2 | location | rule | verdict | effort |
| 3 | location | rule | verdict | effort |
Stale: N (remove immediately) | Unable to verify: N