go-nolint-audit
Skill19 starsChanged 8 months agoMITView on GitHub
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.
In this repository53 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/skills/agent-rules/AGENTS.mdAGENTS.md
- .github/workflows/AGENTS.mdAGENTS.md
- pkg/AGENTS.mdAGENTS.md
- agent-ready-goSkill
- agent-rulesSkill
- architecture-designerSkill
- cli-developerSkill
- cloudformation-to-pulumiSkill
- code-reviewerSkill
- commitlintSkill
- commitSkill
- csharp-developerSkill
- decideSkill
- dep-upgradeSkill
- design-principlesSkill
- devops-engineerSkill
- flux-cliSkill
- flux-operator-cliSkill
- golang-proSkill
- javascript-proSkill
- kubernetes-specialistSkill
- lint-fixSkill
- markdownlintSkill
- prSkill
- pull-request-msg-with-ghSkill
- pulumi-arm-to-pulumiSkill
- pulumi-automation-apiSkill
- pulumi-best-practicesSkill
- pulumi-cdk-to-pulumiSkill
- pulumi-cliSkill
- pulumi-componentSkill
- pulumi-escSkill
- pulumi-goSkill
- pulumi-neoSkill
- pulumi-pythonSkill
- pulumi-terraform-to-pulumiSkill
- pulumi-typescriptSkill
- python-proSkill
- reviewSkill
- roadmapSkill
- rust-async-patternsSkill
- rust-best-practicesSkill
- rust-engineerSkill
- scoutSkill
- security-auditSkill
- spring-boot-engineerSkill
- sre-engineerSkill
- sync-websiteSkill
- tailscale-installSkill
- tech-debtSkill
- the-foolSkill
- typescript-proSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 30
If go is not installed, stop and report.
- Distinctive: line 35
Do not proceed without both tools available.
- Very specific: line 70
If nolintlint reports the directive as unused, it is stale.
- Distinctive: line 75
If golangci-lint fails for reasons other than the target rule (build errors, missing deps), skip the directive and report as "unable to …
- Distinctive: line 150
White (verdict): REMOVE | KEEP | REWRITE JUSTIFICATION [reasoning]
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- Copyright 2025-2026 Richard Shade. Licensed under Apache-2.0. --><!-- SPDX-License-Identifier: Apache-2.0 -->Go Nolint Audit
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.
Prerequisite check
go version 2>/dev/null && golangci-lint --version 2>/dev/nullIf go is not installed, stop and report. If golangci-lint is
missing:
- Install from https://golangci-lint.run/welcome/install/
Do not proceed without both tools available.
Discover nolint directives
grep -rn '//nolint' --include='*.go' . | grep -v vendor/Match all variants: //nolint (bare), //nolint:rule,
//nolint:rule1,rule2. For each directive, capture:
- File and line number
- Suppressed rule(s), or "bare" if no rule specified
- Justification comment (text after
//nolint:rule //if present) - Surrounding code context (~5 lines)
Bare //nolint (no rule) suppresses everything — flag for Phase 2
automatically. If zero directives found, report a clean codebase
and stop.
Phase 1: Mechanical verification
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:
- Stale — rule no longer triggers. Safe to remove.
- Active — rule still triggers. Moves to Phase 2.
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.
Phase 2: Adversarial debate
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:
- Fixability — how easy to fix the code instead of suppressing?
- 5 = trivial (extract function, rename, add constant)
- 3 = moderate (restructure logic, split function)
- 1 = architectural change required
- Justification quality — how convincing is the comment?
- 5 = no comment, or vague ("complexity is inherent", "needed")
- 3 = explains situation but not why fixing is worse
- 1 = specific, compelling reason
Score = Fixability x Justification quality. Consult
references/go-nolint-patterns.md for scoring guidance.
Debate the top 3 by score:
- Red (remove): argues the nolint should be removed and the code fixed. Must propose a concrete diff. Challenges the justification.
- Blue (keep): argues the nolint is correct. Must add reasoning beyond the existing comment. Points out risks of the proposed fix.
- White (judge): evaluates on evidence. Decides: remove, keep, or rewrite justification.
Debate rules
- Red and Blue must cite specific code, not generalities
- Red must provide a concrete diff, not just "this could be simpler"
- Blue cannot simply repeat the existing justification
- White's decision is final
Output format
Phase 1
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 errorPhase 2
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]
Summary
| # | 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
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

