Sonarqube Remediation

See subagent-workflow.md for concrete prompt templates.

Scope

• Use the bundled REST helper scripts to retrieve SonarQube data.
• Treat SonarQube Server as the source of findings.
• Keep tokens, .env files, and machine-local MCP config out of commits.
• Use this skill for subagent-oriented data gathering, issue triage inputs, helper commands, and SonarQube-specific reference material.
• Leave final remediation judgment, local verification, commit creation, PR creation, and cleanup decisions to the calling agent.

Subagent routing

Launch these in parallel when their inputs do not depend on each other.

Shell compatibility

• Bash/zsh: use python3.
• Windows PowerShell: prefer py -3; use python only if py is unavailable.
• Keep script paths relative and with forward slashes so the same commands work across shells.

Required environment

• SONARQUBE_URL
• SONARQUBE_TOKEN
• Subagents should use the caller's existing shell environment. Never paste secret values into prompts, markdown, or commits.

Quick start

Use these as the exact helper commands passed to the Sonar data-collection subagents.

Project summary:

python3 .config/shared/skills/sonarqube-remediation/scripts/sonar_fetch_summary.py --project-key <project-key>

py -3 .config/shared/skills/sonarqube-remediation/scripts/sonar_fetch_summary.py --project-key <project-key>

Open issues:

python3 .config/shared/skills/sonarqube-remediation/scripts/sonar_fetch_issues.py --project-key <project-key> --types BUG,CODE_SMELL --statuses OPEN,CONFIRMED --max-pages 2

py -3 .config/shared/skills/sonarqube-remediation/scripts/sonar_fetch_issues.py --project-key <project-key> --types BUG,CODE_SMELL --statuses OPEN,CONFIRMED --max-pages 2

Duplication details:

python3 .config/shared/skills/sonarqube-remediation/scripts/sonar_fetch_duplications.py --project-key <project-key> --max-files 10 --buffer-percent 20

py -3 .config/shared/skills/sonarqube-remediation/scripts/sonar_fetch_duplications.py --project-key <project-key> --max-files 10 --buffer-percent 20

If the helper output disagrees with the UI or a manual request, compare against this raw API form:

curl -s -u "$SONARQUBE_TOKEN:" "$SONARQUBE_URL/api/issues/search?componentKeys=<project-key>&types=BUG,CODE_SMELL&statuses=OPEN,CONFIRMED&ps=100"

Duplication remediation workflow

Use this workflow when the goal is to reduce duplicated lines in a project.

1. Gather duplication data.

   Spawn an execution-oriented subagent to run sonar_fetch_duplications.py. The script returns:

   • Project-level overview: total LOC, total duplicated lines, current density, removal target with buffer
   • Top files ordered by most duplicated lines
   • Per-file duplication blocks: which lines are duplicated and which other component shares them

2. Check the removal target.

   The script calculates an effective_lines_to_remove that includes a configurable buffer (default 20%). The buffer accounts for refactoring that may introduce some new duplication while removing more (e.g., extracting a shared utility might itself appear as a small duplication block).

3. For each file, check the local codebase.

   Spawn an explore subagent to:

   • Read the duplicated lines in the source file
   • Identify the peer component that shares those lines
   • Search the codebase for an existing shared solution (utility, base class, shared module)
   • Note whether the duplication is in a sensitive area (auth, crypto, migrations)

4. Get an architectural recommendation from the oracle.

   When no existing shared solution is found, spawn an oracle subagent with the duplication context (file pairs, line ranges, code snippets, module boundaries). The oracle will:

   • Recommend the simplest viable consolidation approach with trade-off analysis
   • Provide effort estimates (S/M/L/XL) for each option
   • Assess coupling risk and "when to reconsider" triggers
   • Flag cases where accepting the duplication is the right call

   The oracle is read-only and zero-shot — give it complete context in a single prompt. Its recommendation is advisory; the user makes the final decision.

5. Present the plan to the user.

   For each duplication group, present:

   • The oracle's primary recommendation with rationale
   • Alternative approaches if trade-offs are materially different
   • The option to accept the duplication

   The agent must not choose a consolidation approach without user approval.

6. Implement file by file, starting with the file that has the most duplicated lines. After each file:

   • Run local verification (build, lint, tests)
   • Re-check the duplication count to track progress toward the removal target

Conservative decision rules

• Prefer explicitly requested issue keys when provided by the caller.
• Otherwise favor small, local, low-risk fixes over broad cleanup.
• Be cautious with auth, crypto, access control, data migrations, concurrency-sensitive code, and large cross-package duplication work.
• If helper output disagrees with the UI or raw API data, stop and reconcile the mismatch before changing code.
• If the repo cannot locally verify a fix, surface the limitation instead of guessing.

Optional tooling

• SonarQube MCP server: useful for richer agent workflows, but optional here because MCP is global, not per skill.
• sonar CLI: useful if installed locally, but not the required contract for this skill.
• sonar-scanner: optional for CI-managed analysis, not required for this skill's local workflow.

Reading order

In this reference