Static Analysis & Linter Triage

Expert skill for managing static analysis, PR triage, and linting feedback loops across any programming language.

Quick Check

• Run pre-commit linters locally
• Classify CI lint failures by severity
• Auto-fix safe style/formatting issues
• Document every suppression with a valid reason
• File issues for complex architectural findings

When to Use

• Before committing changes (local linting).
• When CI quality gates or linting workflows fail.
• During PR reviews to triage static analysis findings.
• When integrating new languages or linters into a project.

Pre-commit Workflow

Always run local linters before pushing to minimize CI round-trips.

1. Detect Changes: Identify files modified in the current session.
2. Run Targeted Linters: Use tools like markdownlint, shellcheck, or language-specific linters (e.g., eslint, ruff) on changed files.
3. Verify Quality Gate: Run ./scripts/quality_gate.sh (if available) to ensure all local checks pass.

CI Integration

Read linter output from CI artifacts and PR annotations to identify regressions.

• Check CI Summary: Read ci-summary.md or GitHub Action logs.
• Inspect Annotations: Look for line-specific comments from automated tools (Codacy, SonarCloud, GitHub Actions).
• Match to Source: Map CI errors back to local files and line numbers.

Agent Triage Workflow

Follow this structured process when responding to analysis findings:

1. Classify Severity:
   • Error: Must be fixed or formally suppressed. Blocks merge.
   • Warning: Should be fixed if possible. Indicates potential future issues.
2. Auto-fix Safe Findings:
   • Immediately apply automated fixes for formatting (Prettier, gofmt), imports (ruff, isort), or simple style rules.
3. Handle Complex Findings:
   • If a fix is non-trivial or requires architectural changes, file a follow-up issue and document the technical debt.
4. Suppressions:
   • Never suppress an error without documenting why.
   • Use the Required Comment Format.

Linter Tool Registry

Codacy Git-Aware Analysis

Use the Codacy Analysis CLI for targeted pre-commit and PR-scoped analysis:

# Pre-commit: analyze only staged files
codacy-analysis analyze --staged --output-format json

# Branch analysis: all changes vs merge base
codacy-analysis analyze --diff --output-format json

# PR analysis: changes vs PR target branch
codacy-analysis analyze --pr --output-format json

# Combine with specific tools
codacy-analysis analyze --staged --tool Ruff --tool ESLint9 --output-format json

When to use:

• --staged — Before committing; catches issues in exactly the code you're about to commit
• --diff — During development; sees all uncommitted + committed changes on the branch
• --pr — During PR review; compares against the PR's target branch

Parse results with jq for triage:

# Count issues by severity
codacy-analysis analyze --staged --output-format json | jq '.issues | group_by(.severity) | map({severity: .[0].severity, count: length})'

# Get critical/high only
codacy-analysis analyze --staged --output-format json | jq '[.issues[] | select(.severity == "Error" or .severity == "High")]'

Codacy Integration

If codacy.yml or a Codacy project exists:

1. Read PR Comments: Codacy posts findings as PR comments. Treat these as blocking if they are categorized as "Issues".
2. Triage via CLI: Use codacy pull-request to fetch and ignore false positives if the dashboard is not accessible.
3. Configuration: Check .codacy.yml in the root for project-specific rules.

Suppression Guidelines

When suppressing a linter finding (e.g., via eslint-disable, noqa, or # shellcheck disable), you MUST include a comment in the following format:

[tool-disable] <rule-id>: <reason> -- <agent-id> (<date>)

Example:

# shellcheck disable=SC2034: Variable is used in sourced lib -- Jules (2025-05-15)
UNUSED_VAR="internal"

Rationalizations

Red Flags

• Suppressing lint errors without a documented reason.
• Pushing code that fails local ./scripts/quality_gate.sh.
• Ignoring "style" findings that affect readability (e.g., inconsistent naming).
• Manually fixing formatting instead of using automated tools.

See Also

• code-review-assistant — PR review workflow with code smell detection
• codacy — Local Codacy Analysis CLI for static analysis
• codacy — Codacy CLI for local analysis and cloud data queries

Voice & Context

• Default: professional + blog
• Reference: voice-profiles skill for definitions and auto-detection.