go-lint-audit

name	go-lint-audit
description	WHEN: User wants to run linting on their Go project, understand lint findings, improve their golangci-lint configuration, or asks "what's wrong with my code?" from a linting perspective. WHEN NOT: Deep code quality audit (use go-code-audit), or auto-fixing lint issues (use /lint-fix command).
license	MIT

Go Lint Audit

Extended lint analysis with human-readable explanations. Wraps golangci-lint with better categorization, explanations, and configuration recommendations.

What It Does

1. Runs golangci-lint with comprehensive linter set
2. Groups findings by category and severity
3. Explains each finding in plain language with fix examples
4. Recommends config improvements for .golangci.yml

Steps

API Integration (Optional)

If GOPHER_GUIDES_API_KEY is set, verify it:

curl -s -H "Authorization: Bearer $GOPHER_GUIDES_API_KEY" \
  https://gopherguides.com/api/gopher-ai/me

If not set, local analysis tools (go vet, staticcheck, golangci-lint) still provide comprehensive analysis. Set the key for enhanced API-powered insights. Get your key at gopherguides.com.

1. Check Configuration

# Find existing config
ls .golangci.yml .golangci.yaml .golangci.toml 2>/dev/null

# If no config exists, note it — will recommend one

2. Run Analysis

# Run with all findings shown
golangci-lint run \
  --max-issues-per-linter 0 \
  --max-same-issues 0 \
  --out-format json \
  ./... 2>&1

If golangci-lint is not installed:

# Install
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

3. Categorize Findings

Group findings into categories:

Category	Linters	Severity
Bugs	govet, staticcheck, gosec	🔴 Critical
Error Handling	errcheck, errorlint	🔴 Critical
Performance	prealloc, bodyclose	🟡 Warning
Style	gofmt, goimports, misspell	🟢 Suggestion
Complexity	cyclop, gocognit, funlen	🟡 Warning
Maintainability	gocritic, revive, dupl	🟡 Warning
Security	gosec	🔴 Critical

4. Explain Findings

For each finding, provide:

• What it means in plain language
• Why it matters (bug risk, performance, maintainability)
• How to fix it with a code example
• When to ignore it (if applicable, with //nolint directive)

Example:

#### errcheck: Error return value of `os.Remove` is not checked

**What:** The function `os.Remove()` returns an error that your code ignores.

**Why:** If the file doesn't exist or can't be deleted, your program won't know,
potentially leaving stale files or masking permission issues.

**Fix:**
​```go
// Before
os.Remove(tempFile)

// After
if err := os.Remove(tempFile); err != nil {
    return fmt.Errorf("failed to remove temp file %s: %w", tempFile, err)
}
​```

**Ignore:** Only if the file removal is truly best-effort:
​```go
_ = os.Remove(tempFile) //nolint:errcheck // best-effort cleanup
​```

5. Configuration Recommendations

Suggest .golangci.yml improvements:

# Recommended golangci-lint configuration
linters:
  enable:
    # Bug detection
    - govet
    - staticcheck
    - gosec
    # Error handling
    - errcheck
    - errorlint
    # Style
    - gofmt
    - goimports
    - misspell
    # Complexity
    - cyclop
    - gocognit
    # Maintainability
    - gocritic
    - revive
    - dupl
    # Performance
    - prealloc
    - bodyclose

linters-settings:
  cyclop:
    max-complexity: 15
  gocognit:
    min-complexity: 20
  funlen:
    lines: 80
    statements: 50
  goimports:
    local-prefixes: github.com/yourorg
  errcheck:
    check-type-assertions: true
    check-blank: true

issues:
  exclude-use-default: false
  max-issues-per-linter: 0
  max-same-issues: 0

run:
  timeout: 5m

Output Format

## Lint Audit Report

**Project:** {name}
**Linters:** {count} active
**Total Findings:** {count}

### Summary

| Category | Count | Severity |
|----------|-------|----------|
| Bugs | {n} | 🔴 |
| Error Handling | {n} | 🔴 |
| Performance | {n} | 🟡 |
| Style | {n} | 🟢 |
| Complexity | {n} | 🟡 |

### Findings by Category

#### 🔴 Bugs ({n})
{detailed findings with explanations}

#### 🔴 Error Handling ({n})
{detailed findings with explanations}

...

### Configuration Recommendations
{suggested .golangci.yml changes}

### Quick Fixes Available
{list of auto-fixable issues with `golangci-lint run --fix`}

Gopher Guides API Integration

Note: API calls send source code to gopherguides.com for analysis. Ensure your organization's policy permits external code analysis.

For full API usage examples, see API Usage Reference.

Helper Script

After installation via install.sh, scripts are at .github/skills/scripts/. Run the full audit including lint + API:

bash .github/skills/scripts/audit.sh

Severity Configuration

After installation via install.sh, lint categories map to severity levels at .github/skills/config/severity.yaml. See the Setup Guide for details.

References

• Existing gopher-ai command: plugins/go-dev/commands/lint-fix.md
• golangci-lint documentation
• Go Code Review Comments

---

Powered by Gopher Guides training materials.