sonarqube-autofix v2.0.0A

Immutable. This exact content is served forever at /api/v1/blob/13f68a616f8835c4.

---
name: sonarqube-autofix
license: MIT
description: Use when analyzing SonarQube issues and creating SPEC SDDs with the proposed fixes. Classifies issues by type (bug, code smell, security) and generates `.specs/SPEC-{YYYYMMDD}-{issue-key}-{type}.md` for `execute-tdd-spec` to implement. Supports Community, Enterprise, and custom SonarQube deployments via environment variables. Do NOT use for general code review without SonarQube (use code-review-and-quality), for whole-repo quality interventions without SonarQube (use quality-test-implementation), or for non-SonarQube static analysis tools. Part of the afonsoft/skills collection.
metadata:
  version: 2.0.0
  visibility: public
  author: afonsoft
  url: https://github.com/afonsoft/skills
  subagent: 'false'
  user-invokable: 'true'
  argument-hint: <project-name> [--new-code-only] [--issues=<issue-id1,issue-id2,...>]
  openclaw: '{"requires":{"bins":["sonar-scanner"]},"envVars":[{"name":"SONARQUBE_CUSTOM_URL","required":false},{"name":"SONARQUBE_CUSTOM_TOKEN","required":false},{"name":"SONARQUBE_ENTERPRISE_TOKEN","required":false},{"name":"SONARQUBE_ENTERPRISE_URL","required":false},{"name":"SONARQUBE_OPEN_TOKEN","required":false},{"name":"SONAR_TK","required":false},{"name":"SONARQUBE_OPEN_URL","required":false}]}'
---

# SonarQube Auto-Fix

## When to Use

- User asks or mentions this skill in English (e.g., "use /sonarqube-autofix", "run sonarqube-autofix").
- O usuário pede ou menciona esta skill em português (ex.: "use /sonarqube-autofix", "execute sonarqube-autofix").

## Purpose

Analyze issues reported by SonarQube, **regardless of language or framework**, classify them by type, and create approved SPEC SDDs that describe the fixes. The actual implementation of each SPEC is delegated to `/execute-tdd-spec`.

The process is:
1. **Issue analysis** — download and inspect unresolved SonarQube issues.
2. **Classification** — group issues by type: `bug`, `code smell`, or `security`.
3. **SPEC generation** — write one SPEC SDD per issue (or per small, related group) using `references/spec-sdd-template.md`.
4. **Hand-off** — mark each SPEC as `Approved` and invoke `/execute-tdd-spec` to implement the fixes.

## ⚙️ Environment Variable Configuration

The skill supports multiple SonarQube editions through environment variables. Detection is automatic based on the availability of the variables (in priority order):

> **⚠️ IMPORTANT:** For security, NEVER read, print, or inspect the value of environment variables that contain tokens. The most you may know is which variable the token is stored in. Use the variables directly in commands without accessing their contents.

### Available Variables

#### For Custom URL (Highest Priority)
- `SONARQUBE_CUSTOM_URL`: Base URL of the custom SonarQube
- `SONARQUBE_CUSTOM_TOKEN`: Authentication token for the custom SonarQube
- `SONARQUBE_CUSTOM_EDITION`: Edition of the custom SonarQube (`open` or `enterprise`, default: `open`)

#### For SonarQube Enterprise
- `SONARQUBE_ENTERPRISE_TOKEN`: Authentication token for SonarQube Enterprise
- `SONARQUBE_ENTERPRISE_URL`: Base URL of SonarQube Enterprise (required, no fallback)

#### For SonarQube Open (Default)
- `SONARQUBE_OPEN_TOKEN`: Authentication token for SonarQube Open (preferred)
- `SONAR_TK`: Authentication token for SonarQube Open (fallback for compatibility, used only if SONARQUBE_OPEN_TOKEN is not set)
- `SONARQUBE_OPEN_URL`: Base URL of SonarQube Open (required, no fallback)

### Branch Support

Enterprise and Custom editions with `enterprise` edition automatically support the `branch` parameter in the API. The skill automatically detects the current branch using `git branch --show-current`.

## 🌍 Supports Any Stack
- ✅ **Languages:** Java, Kotlin, Python, JavaScript, TypeScript, C#, C++, Go, Ruby, PHP, Scala, PLSQL, VB.NET and others
- ✅ **Frameworks:** Spring, Django, Flask, FastAPI, Express, React, Vue, Angular, .NET, ASP.NET, Gin, Rails, etc.
- ✅ **Any test tool** that generates coverage reports
- ✅ **Any dependency manager** (Maven, Gradle, npm, pip, dotnet, etc.)

## 🔍 Automatic Stack Detection

The skill automatically detects the project's stack by analyzing configuration files. Load the script `references/detect-stack.sh` to determine the stack and configure the appropriate commands.

### Detection Patterns

| File | Stack | Manager | Test Tool | Coverage Tool |
|---|---|---|---|---|
| `pom.xml` | Java/Kotlin | Maven | Maven Surefire/Failsafe | JaCoCo |
| `build.gradle` / `build.gradle.kts` | Java/Kotlin | Gradle | Gradle Test | JaCoCo |
| `package.json` | JavaScript/TypeScript | npm/yarn/pnpm | Jest/Vitest/Mocha | Istanbul |
| `requirements.txt` / `pyproject.toml` | Python | pip | pytest | Coverage.py |
| `.csproj` / `.sln` | C#/.NET | dotnet | dotnet test | OpenCover/Cobertura |
| `go.mod` | Go | go mod | go test | go test -cover |
| `Gemfile` | Ruby | bundler | rspec/minitest | SimpleCov |
| `composer.json` | PHP | composer | phpunit | phpunit |
| `build.sbt` | Scala | sbt | sbt test | sbt coverage |

### Detection Script

Load the script `references/detect-stack.sh` to automatically detect the project's stack and configure the appropriate commands.

## Angular-Specific Support

### Angular Detection
- File: `angular.json` or `angular-cli.json`
- Manager: npm, yarn, pnpm
- Test Framework: Karma + Jasmine or Jest
- Coverage Tool: Istanbul (ng test --code-coverage)

### Angular Commands

```bash
# Tests with coverage
ng test --code-coverage --watch=false

# Linting
ng lint

# Formatting
npx prettier@<VERSION> --write src/
npx eslint@<VERSION> --fix src/

# Build for validation
ng build --configuration=production
```

### Angular Scripts
- `references/validate-angular.sh` — Angular validation (ng lint, ng test, prettier, eslint)

### Angular Test Template
- `references/templates/test-angular.md` — Template for Karma/Jasmine tests with TestBed

## C# .NET-Specific Support

### C# .NET Detection
- File: `.csproj` or `.sln`
- Manager: dotnet CLI
- Test Framework: xUnit, NUnit, MSTest
- Coverage Tool: dotnet test /p:CollectCoverage=true

### C# .NET Commands

```bash
# Tests with coverage
dotnet test /p:CollectCoverage=true /p:CoverageFormat=cobertura

# Linting and analysis
dotnet build /p:RunAnalyzersDuringBuild=true

# Formatting
dotnet format

# Package restore
dotnet restore
```

### C# .NET Scripts
- `references/validate-csharp.sh` — C#/.NET validation (dotnet build, dotnet test, dotnet format)

### C# .NET Test Template
- `references/templates/test-csharp.md` — Template for xUnit/Moq tests

## SonarQube Local Validation

### Local Validation Script
Load the script `references/sonar-local-scan.sh` to run SonarQube locally and revalidate fixes before committing.

```bash
# Run local scan
bash references/sonar-local-scan.sh
```

### Local SonarQube Configuration
The `sonar-local-scan.sh` script requires:
- `sonar-scanner` installed (available at https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/scanners/sonarscanner/)
- Java 17+ and `jq`
- `sonar-project.properties` file in the project root (optional, script configures automatically)

### sonar-scanner Installation

```bash
# Linux/macOS (manual): unzip the SonarScanner ZIP and add <path>/bin to PATH
export PATH="$HOME/sonar-scanner-<version>/bin:$PATH"

# Or use this repository's installer
./install-skill-tools.sh --sonar
```

### Example sonar-project.properties
```properties
sonar.projectKey=my-project
sonar.sources=src
sonar.tests=tests
sonar.exclusions=**/node_modules/**,**/dist/**,**/bin/**,**/obj/**
sonar.coverage.exclusions=**/*Tests.cs,**/Program.cs
sonar.cs.vscoveragexml.reportPaths=coverage.xml
sonar.javascript.lcov.reportPaths=coverage/lcov.info
```

## Workflow

### Pre Steps
- Save the time you started running the skill to measure the time spent.
- When finishing the run, save the end time to calculate the total time spent.
- Compare the time spent with the "effort" estimated in the issue to evaluate the skill's efficiency (report how many % of time saved or lost relative to the estimated effort).

### Phase 1: Analysis and Preparation

1. **Detect Project Stack**
   - Load the script `references/detect-stack.sh` to automatically detect the stack
   - The script returns: `STACK`, `BUILD_TOOL`, `TEST_FRAMEWORK`, `COVERAGE_TOOL`
   - Configure the appropriate commands based on the detected stack
   - If automatic detection is not possible, ask the user

2. **Verify issues file**
   - Check the project name, usually it is the workspace folder name.
   - If it is not at the project root, create the `.sonar_devin_auto_fix/` folder
   - **⚠️ CRITICAL SECURITY:** Never print the value of environment variables that contain tokens or secrets. NEVER read token values into your memory — the most you may know is which environment variable the token is stored in. Use the variables directly in bash commands without ever inspecting their contents.
   - Download the project's issues:
     If the user specifies the project name, use it; otherwise try to use the workspace folder name, and if that is still not possible, ask the user for the project name.
     If the user provides the issues to be fixed, query using the `issues` parameter and pass a csv list with the issue IDs; otherwise download all unresolved issues from the project using the SonarQube API.
     If the user requests to fix only new issues, download the unresolved issues and add the `inNewCodePeriod` filter set to true.

     **Automatic SonarQube edition detection:**
     The skill automatically detects which edition to use based on the available environment variables (in priority order):

     1. **Custom URL** (highest priority): If `$SONARQUBE_CUSTOM_URL` is set
     2. **Enterprise**: If `$SONARQUBE_ENTERPRISE_TOKEN` is set
     3. **Open**: If `$SONARQUBE_OPEN_TOKEN` or `$SONAR_TK` is set
     4. **Error**: If none of the above, abort and request the environment variables to be configured (there is no automatic/fallback URL).

     **Download issues with automatic detection:**
     Load the reference script `references/download-issues.sh` and execute it.

   - Indent the downloaded issues file using the script `references/jsonf.sh`
   - Confirm that `.sonar_devin_auto_fix/sonarqube_issues.json` exists and is parseable
   - Base all fixes exclusively on the issues listed in that JSON

2. **Create ToDo Board**
   - Create the file `.sonar_devin_auto_fix/SONAR_FIX_TODO_BOARD.md`
   - Use the format:
     ```markdown
     # SonarQube Review ToDo Board

     ## SonarQube Issues Checklist

     - [ ] Issue <ID> — Rule: <RuleKey> — File: `<path/to/file>` — Line: <line>
           Summary: <short issue message>
     ```
   - Group by file if possible
   - Sort by severity (Blocker → Critical → Major → Minor → Info)

### Phase 2: Classify Issues

For each downloaded issue, classify it into one of the following types and record the classification in the ToDo Board:

| Type | SonarQube categories |
| --- | --- |
| `bug` | Bugs (`BUG`) and reliability issues |
| `code smell` | Code Smells (`CODE_SMELL`) and maintainability issues |
| `security` | Vulnerabilities (`VULNERABILITY`) and Security Hotspots (`SECURITY_HOTSPOT`) |

Add the type to each line of `SONAR_FIX_TODO_BOARD.md`:

```markdown
- [ ] Issue <ID> — Type: <bug | code smell | security> — Rule: <RuleKey> — File: `<path/to/file>` — Line: <line>
      Summary: <short issue message>
```

Sort the board by: `security` → `bug` → `code smell`, then by severity.

### Phase 3: Generate SPEC SDDs

For each issue (or small, related group of the same type), create an approved SPEC SDD in `.specs/SPEC-{YYYYMMDD}-{issue-key}-{type}.md` using `references/spec-sdd-template.md`:

1. **Metadata** — set `Type` to the issue type (`Bugfix` for `bug`, `Refactor` for `code smell`, `Security` for `security`), `Status: Approved`, and map the SonarQube rule and file.
2. **User Story** — describe the problem exposed by SonarQube and the value of the fix.
3. **Scope** — one issue per SPEC, unless several identical issues are safely grouped (e.g., the same rule in the same file).
4. **Technical Context** — list files to read (source file, existing tests) and the affected lines.
5. **Requirements** — one or more numbered requirements translating the SonarQube rule to the expected code state.
6. **Acceptance Criteria** — `Given...when...then` plus "SonarQube no longer reports issue <ID>".
7. **Task Plan** — the fix steps, validation commands, and a link to `SONAR_FIX_TODO_BOARD.md`.

Mark each generated SPEC as `Status: Approved`. Do **not** implement the code in this skill.

### Phase 3.5: Hand off to `/execute-tdd-spec`

After all SPECs are approved, invoke `/execute-tdd-spec` for each one, in the order of the sorted ToDo Board. The implementation skill will follow the red-green-refactor cycle using the generated SPECs as source of truth.

### Phase 4: Documentation and Finalization

1. **Update .gitignore**
   - Open `.gitignore` at the project root
   - Add the line: `.sonar_devin_auto_fix/**`
   - Only if an equivalent does not already exist

2. **Generate Review Guide**
   - Create `.sonar_devin_auto_fix/SONAR_FIX_REVIEW_NOTES.md`
   - Include sections:
     - **Summary of changes**: number of issues fixed and types of fixes
     - **How to review**: instructions for the developer to review the changes
     - **Points of attention**: sensitive logic that was changed
     - **Tests**: how to run tests and coverage
     - **Post-review verification**: final validations

3. **Final validation**
   - The SonarQube scan will be run by the CI/CD pipeline after the merge
   - Confirm that the code is clean and tests are passing

4. **Generate Metrics Dashboard**
   - Create `.sonar_devin_auto_fix/SONAR_FIX_METRICS.html`
   - Include:
     - Time spent vs estimated effort (in %)
     - Number of issues fixed by type (bug, code smell, vulnerability, hotspot)
     - Coverage before/after
     - Regressions avoided
     - Detected stack and tools used

## 🛠️ Integrated External Tools

The skill automatically integrates external tools per stack to validate and format the code after fixes.

### Linters by Stack

| Stack | Linter | Command |
|---|---|---|
| Java/Kotlin | Checkstyle, PMD | `mvn checkstyle:check pmd:check` |
| JavaScript/TypeScript | ESLint | `npx eslint@<VERSION> src/` |
| Python | Pylint, Flake8 | `python -m pylint src/` |
| C#/.NET | StyleCop, Roslyn Analyzers | `dotnet build /p:RunAnalyzersDuringBuild=true` |
| Go | golint, golangci-lint | `golangci-lint run` |
| Ruby | RuboCop | `bundle exec rubocop` |
| PHP | PHPStan | `vendor/bin/phpstan analyse` |
| Scala | Scalastyle, Scapegoat | `sbt scalastyle scapegoat` |

### Formatters by Stack

| Stack | Formatter | Command |
|---|---|---|
| Java/Kotlin | Spotless, Google Java Format | `mvn spotless:apply` |
| JavaScript/TypeScript | Prettier | `npx prettier@<VERSION> --write src/` |
| Python | Black, isort | `python -m black src/` |
| C#/.NET | dotnet format | `dotnet format` |
| Go | gofmt, goimports | `gofmt -w .` |
| Ruby | Rufo | `bundle exec rufo` |
| PHP | PHP CS Fixer | `vendor/bin/php-cs-fixer fix` |

### Coverage Tools by Stack

| Stack | Tool | Command |
|---|---|---|
| Java/Kotlin | JaCoCo | `mvn jacoco:report` |
| JavaScript/TypeScript | Istanbul | `npx vitest@<VERSION> run --coverage` |
| Python | Coverage.py | `python -m coverage run -m pytest` |
| C#/.NET | OpenCover, Cobertura | `dotnet test /p:CollectCoverage=true /p:CoverageFormat=cobertura` |
| Go | go test -cover | `go test -cover ./...` |
| Ruby | SimpleCov | `bundle exec rspec --coverage` |
| PHP | phpunit --coverage-clover | `vendor/bin/phpunit --coverage-clover=coverage.xml` |
| Scala | sbt coverage | `sbt clean coverage test coverageReport` |

### SonarLint and SonarScanner

The skill may use SonarLint and SonarScanner for local validation before committing:

**SonarLint (IDE Integration):**
- Available for IntelliJ IDEA, VS Code, Eclipse
- Validates code in real time
- Can be invoked via command line for batch validation

**SonarScanner CLI:**
- For local scans before push
- Offline validation of fixes
- Command: `sonar-scanner -Dsonar.projectKey=<project> -Dsonar.sources=src`

### Validation Scripts

The skill loads reference scripts for automatic validation per stack:

- `references/validate-java.sh` — Java/Kotlin validation (Checkstyle, PMD, Spotless, JaCoCo)
- `references/validate-js.sh` — JavaScript/TypeScript validation (ESLint, Prettier, Vitest)
- `references/validate-python.sh` — Python validation (Pylint, Flake8, Black, pytest)
- `references/validate-csharp.sh` — C#/.NET validation (Roslyn Analyzers, dotnet format, dotnet test)
- `references/validate-go.sh` — Go validation (golangci-lint, gofmt, go test)
- `references/validate-ruby.sh` — Ruby validation (RuboCop, Rufo, rspec)
- `references/validate-php.sh` — PHP validation (PHPStan, PHP CS Fixer, phpunit)
- `references/validate-scala.sh` — Scala validation (Scalastyle, Scapegoat, sbt)

## 🎨 Test Templates by Stack

The skill generates tests automatically based on stack-specific templates. Load the appropriate template from the `references/templates/` folder:

- `test-java.md` — Template for JUnit/Mockito tests
- `test-kotlin.md` — Template for KotlinTest/Mockk tests
- `test-python.md` — Template for pytest/unittest tests
- `test-javascript.md` — Template for Jest/Vitest tests
- `test-typescript.md` — Template for TypeScript tests
- `test-csharp.md` — Template for xUnit/Moq tests
- `test-go.md` — Template for Go tests
- `test-ruby.md` — Template for RSpec/Minitest tests
- `test-php.md` — Template for PHPUnit tests
- `test-scala.md` — Template for ScalaTest/ScalaCheck tests

### Tests and Coverage
- ✅ **100% coverage of modified lines** (verified in coverage report)
- ✅ **No coverage exclusions**, such as:
  - Comments: `// NOSONAR`, `// no sonar`, `# noqa`, `# pragma: no cover`, etc.
  - Decorators/Attributes: `@IgnoreCoverage`, `ExcludeFromCodeCoverage`, `@Suppress`, etc.
  - Compiler pragmas: `#pragma`, etc.
  - IMPORTANT: If the file already has a coverage exclusion, remove it and implement tests for the fix as well as for the rest of the file's code, ensuring full coverage.
- ✅ Remove SonarQube scanner files that may be present, such as `sonar-project.properties`, `sonar-scanner.properties`, etc. Also remove other scanners, such as the `SonarScanner for Maven` usually present in the POM.xml, since our pipeline is autonomous and does not depend on these files to work. (For now, keep only SonarQube-related configurations in `.csproj` files).
- ✅ All tests passing
- ✅ Coverage report available (formats: OpenCover, JaCoCo, Cobertura, Istanbul, etc.)

### Code Quality
- ✅ No new code smells or SonarQube violations
- ✅ No functional regressions
- ✅ No obvious performance problems
- ✅ Minimal, targeted changes
- ✅ Code follows project conventions and standards
- ✅ No unnecessary changes in areas unrelated to the issue

### Business Logic
- ✅ **Do not change** business logic without extreme necessity
- ✅ If it is necessary to change sensitive points (business rules, critical calculations, main flows):
  - Minimize the change
  - Document clearly in the review guide
  - Justify why it was unavoidable
  - Add specific tests to validate the change

### Dependencies
- ✅ **Do not add** unnecessary dependencies
- ✅ Stay within the scope of SonarQube fixes
- ✅ If adding a dependency is absolutely necessary, justify and document it
- ✅ Check that there are no conflicts with existing dependencies

## Completion Checklist

- [ ] All issues analyzed and categorized in SONAR_FIX_TODO_BOARD.md
- [ ] All issues fixed with 100% test coverage
- [ ] All tests passing
- [ ] .gitignore updated with `.sonar_devin_auto_fix/**`
- [ ] SONAR_FIX_REVIEW_NOTES.md generated with complete instructions
- [ ] No new issue introduced (verified via code review and tests)

## Useful Commands (Examples by Stack)

### ⚠️ Important: Isolated Environments with Required Parameters

**Commands are configured to force isolated environments. The isolation prefix is required, but you may add more parameters after it.**

**Rule:** Keep the isolation parameter (e.g. `-Dmaven.repo.local=./.m2/repository`), but you may add more flags.

### Java / Kotlin (Maven)

```bash
# ✅ ALLOWED - Mandatory isolation + additional parameters
mvn -Dmaven.repo.local=./.m2/repository clean test
mvn -Dmaven.repo.local=./.m2/repository -DskipTests=false jacoco:report
mvn -Dmaven.repo.local=./.m2/repository -Dorg.slf4j.simpleLogger.defaultLogLevel=debug clean test

# ❌ NOT ALLOWED - No isolation
mvn clean test
```

### Java / Kotlin (Gradle)

```bash
# ✅ ALLOWED - Mandatory isolation + additional flags
gradle --gradle-user-home ./.gradle test
gradle --gradle-user-home ./.gradle test --info
gradle --gradle-user-home ./.gradle clean build -x test

# ❌ NOT ALLOWED - No isolation
gradle test
```

### JavaScript / TypeScript / Node.js

```bash
# npm ✅ ALLOWED
npm install --no-save
npm install --no-save --verbose
npm test -- --coverage --verbose

# yarn ✅ ALLOWED
yarn install --offline
yarn install --offline --verbose

# pnpm ✅ ALLOWED
pnpm install
pnpm install --verbose

# npx ✅ ALLOWED only with pinned versions
npx vitest@<VERSION> run --coverage
npx eslint@<VERSION> src/
```

### Python

```bash
# Create venv (if not exists) ✅ ALLOWED
python -m venv .venv
python -m venv .venv --upgrade-deps

# pip with isolation ✅ ALLOWED
python -m pip install -r requirements.txt -q
python -m pip install --target ./.venv/lib -q package-name
python -m pip install --target ./.venv/lib --upgrade package-name

# pytest and coverage ✅ ALLOWED
python -m pytest --cov=src tests/ -v
python -m pytest --cov=src tests/ --cov-report=html
python -m coverage run -m pytest
python -m coverage report --skip-covered
```

### C# / .NET

```bash
# ✅ ALLOWED
dotnet test
dotnet test /p:CollectCoverage=true /p:CoverageFormat=cobertura
dotnet test /p:CollectCoverage=true /p:Exclude="[*Tests]*"
```

### Go

```bash
# ✅ ALLOWED
go test -cover ./...
go test -cover ./... -v
go test -coverprofile=coverage.out ./... -timeout=10m
```

### Ruby / Rails

```bash
# ✅ ALLOWED
bundle install --local
bundle install --local --no-deployment
bundle exec rspec --coverage
bundle exec rspec --coverage -f progress
```

### PHP

```bash
# ✅ ALLOWED
composer install --no-dev
composer install --no-dev --optimize-autoloader
composer install --no-dev --classmap-authoritative
vendor/bin/phpunit --coverage-clover=coverage.xml
vendor/bin/phpunit --coverage-clover=coverage.xml -v
```

### Scala

```bash
# ✅ ALLOWED
sbt clean coverage test coverageReport
sbt clean coverage test coverageReport -Dconfig=test
sbt "test -- -Dverbose=true"
```

## 🧹 Environment Cleanup

When finishing all fixes, run:

```bash
git status
```

Analyze the output and:

- Temporary, build, coverage, or cache files that appear → add to `.gitignore`
- Staged files that **should not** be there → remove with `git restore --staged <file>`
- Confirm that `.sonar_devin_auto_fix/` **does not appear** as staged

> ⚠️ **Do not commit.** Leave the repository clean and organized so the human developer can review and decide what to commit.

### Cleanup of Isolated Environments (Optional)

If the user asks to remove isolated environments after completion, **list the paths first and ask for explicit confirmation** before deleting anything. Do not run `rm -rf` or `find -exec rm -rf` without consent.

```bash
# List what would be removed (do not delete automatically)
echo "The following paths could be removed: .venv .m2 node_modules .npm __pycache__ .pytest_cache"
# Ask the user to confirm before proceeding. Prefer `git clean` for tracked artifacts.
```

**Important:** Verify that the isolated environments are in `.gitignore`:

```bash
# Check if already in .gitignore
grep -E "^\.venv$|^\.m2$|^node_modules$|^__pycache__$" .gitignore

# If not found, add them:
echo ".venv" >> .gitignore
echo ".m2" >> .gitignore
echo "node_modules" >> .gitignore
echo ".pytest_cache" >> .gitignore
echo "__pycache__" >> .gitignore
```

## Important Notes

- 🎯 Work in iterations: one issue at a time, with tests and documentation
- 📝 Keep code clean and aligned with the project's existing standard
- 🔍 Prioritize clarity and maintainability
- ⚠️ Always consider the impact of each change on business logic
- 🧹 **ALWAYS clean the environment when finishing** — no temporary file should remain pending
- ⚡ **Be efficient with time and tokens:** avoid unnecessary reads, excessive exploration, and repetitions. Read only what is strictly necessary to fix the issue at hand. Prefer direct and objective actions. Avoid invoking unnecessary tools — use only what the task requires.
- 🚫 **Do not implement anything beyond what was requested:** fix exclusively the issues listed in `sonarqube_issues.json`. Do not refactor without need, do not improve, do not add features, do not reorganize code that is not directly related to the issue.
- 🚫 **Do not run programming scripts that require human validation before release:** when trying to run scripts, a prompt is presented to the user to decide whether it can be executed, which removes your autonomy and generates more work for the user.

## The Iron Law

```
NO COVERAGE EXCLUSIONS
```

No coverage exclusion may be used to bypass the lack of tests.

**No exceptions:**
- Do not use `// NOSONAR`, `// no sonar`, `# noqa`, `# pragma: no cover`
- Do not use decorators such as `@IgnoreCoverage`, `ExcludeFromCodeCoverage`, `@Suppress`
- Do not use compiler pragmas such as `#pragma` for exclusions
- If the file already has an exclusion, remove it and implement tests for the code
- Ensure 100% coverage of the modified lines

## Common Mistakes

| Mistake | Consequence | How to avoid |
|------|-------------|-------------|
| Add coverage exclusions | Code without tests approved | Implement tests for all modified lines |
| Fix issues without tests | Undetected regressions | Always add unit tests for each fix |
| Change business logic without need | Bug risk | Stay within the scope of the SonarQube issue |
| Do not run linters after fixing | New violations introduced | Run stack linters after each fix |
| Do not clean environment at the end | Temporary files in repo | Run environment cleanup when finishing |
| Print environment variable values | Security violation | NEVER read or print tokens, use variables directly in commands |

## Anti-Patterns

### ❌ "This code is too simple to need a test"

Even simple code can have bugs. TDD applies to any fix, regardless of complexity.

### ❌ "I'll add a coverage exclusion just for this case"

Coverage exclusions violate the quality principle. If the code is too complex to test, refactor it.

### ❌ "SonarQube is wrong, I won't fix it"

SonarQube can have false positives, but most issues are valid. Fix them and discuss legitimate cases with the team.

### ❌ "I'll fix everything at once without tests"

Bulk fixes without tests drastically increase the risk of regressions. Fix one issue at a time with tests.

### ❌ "I don't need to run the local scan, the pipeline will validate"

Local validation saves time and avoids pipeline rejections. Use the `sonar-local-scan.sh` script.

## Adaptations for this catalog

This skill follows the agent catalog standards:
- **Frontmatter** aligned to repo standard: `license: MIT`, `metadata.version`, `metadata.author`, tripartite `description` with explicit `Do NOT use for` clause
- **Language:** English (en-us) for content, technical terms in English
- **Branch policy:** follow `feature/{agent}-{YYYYMMDD}-{short-description}`
- **Git workflow:** branches created from `develop`, PR target is `develop` (not `main`)

## Origin

This skill was created following patterns from `obra/superpowers/skills/writing-skills` and adapted for SonarQube auto-fix workflows across multiple stacks.