/code-quality

name: code-quality
description: "Code quality: cleanup, linting, formatting, quality gates."
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
  - Task
  - Skill
agent: python-general-engineer
routing:
  force_route: true
  not_for: "code review with findings (use review), security scanning (use security)"
  triggers:
    - "code cleanup"
    - "clean up code"
    - "find dead code"
    - "stale TODOs"
    - "unused imports"
    - "remove dead code"
    - "find unused"
    - "tidy code"
    - "lint code"
    - "run ruff"
    - "run biome"
    - "format code"
    - "lint errors"
    - "Python quality"
    - "ruff check"
    - "bandit scan"
    - "mypy check"
    - "python lint"
    - "python quality gate"
    - "check python"
    - "pre-commit check"
    - "quality gate"
    - "lint check"
    - "multi-language lint"
    - "code quality check"
    - "technical debt scan"
  category: code-quality
  pairs_with:
    - review
    - testing
    - comment-quality

Code Quality

Four modes. Select by request signal:

| Signal | Mode | |--------|------| | Dead code, stale TODOs, unused imports, technical debt | Cleanup | | Lint Python/JS/TS, run ruff, run biome, format code | Linting | | Python quality checks, ruff+pytest+mypy+bandit | Python Quality Gate | | Multi-language quality gate, general "quality check" | Universal Quality Gate |

Default: Python-specific requests run Python Quality Gate. General requests run Universal Quality Gate.

---

Mode A: Cleanup

Scan for 9 categories of technical debt: stale TODOs, unused imports, dead code, missing type hints, deprecated functions, naming inconsistencies, high complexity, duplicate code, missing docstrings. Follow `references/code-cleanup.md` for the full 3-phase workflow (SCOPE, SCAN, REPORT).

Key principles:

• Read CLAUDE.md first for project conventions
• Scan only what was requested; ask for a target rather than scanning everything
• Exclude vendor/, node_modules/, .venv/, build/, dist/, generated/, .git/
• Prioritize findings by impact/effort: Quick Wins (auto-fixable, <5 min) > Important (bugs, security) > Polish (style)
• Apply auto-fixes only with explicit user permission; check first, fix, review diff, rerun checks

---

Mode B: Linting

Check or fix Python with Ruff and JavaScript/TypeScript with Biome. Read project instructions, `pyproject.toml`, and `biome.json` first; preserve configured rules.

| Task | Python | JavaScript/TypeScript | |------|--------|----------------------| | Check | `ruff check .` | `npx @biomejs/biome check src/` | | Format check | `ruff format --check .` | Included in Biome check | | Fix lint | `ruff check --fix .` | `npx @biomejs/biome check --write src/` | | Format | `ruff format .` | `npx @biomejs/biome format --write src/` |

Use project environment (`./venv/bin/ruff`). If configured, use `make lint` or `make lint-fix`. Check first; apply fixes only within requested scope. Review `git diff`, undo incorrect fixes, rerun checks. Do not change rules or install new tooling to get a pass.

Common fixes: F401 = remove/use import. I001 = sort imports. E501 = shorten lines. Biome `noVar` = use let/const. `useConst` = mark unchanged bindings.

---

Mode C: Python Quality Gate

Run checks in order. Read repository configuration first; project commands and thresholds override defaults.

**Detect**: Find `pyproject.toml`, `setup.py`, `.python-version`. Check tool availability: ruff and pytest required; mypy and bandit optional unless project requires them.

**Execute**:

| Order | Command | Condition | |-------|---------|-----------| | 1 | `ruff check . --output-format=grouped` | Required | | 2 | `ruff format --check .` | Required | | 3 | `mypy . --ignore-missing-imports --show-error-codes` | If available | | 4 | `pytest -v --tb=short --cov=src --cov-report=term-missing` | Coverage only when configured | | 5 | `bandit -r src/ -ll --format=screen` | If available |

Run all checks even after one fails. Do not skip tests to get a pass.

**Assess**: Prioritize syntax/undefined errors, failing tests, security findings before style. Report per-tool status with actionable file:line diagnostics.

**Fix**: When authorized, run `ruff check . --fix` and `ruff format .`, review diff, rerun checks.

---

Mode D: Universal Quality Gate

Auto-detect languages and run configured checks. Read repository instructions first.

python3 ~/.claude/skills/code-quality/universal-quality-gate/scripts/run_quality_gate.py

Options: `--staged` (pre-commit), `--lang python` (single language), `--fix` (apply fixes), `-v` (verbose).

Language detection uses `hooks/lib/language_registry.json`:

| Language | Markers | Tools | |----------|---------|-------| | Python | pyproject.toml, requirements.txt | ruff, mypy, bandit | | Go | go.mod | gofmt, golangci-lint, go vet | | JavaScript | package.json | eslint, biome | | TypeScript | tsconfig.json | tsc, eslint, biome | | Rust | Cargo.toml | clippy, cargo fmt | | Shell | *.sh | shellcheck |

A gate pass means required tools passed; it does not prove tests, builds, or business behavior passed.

---

Deep References

Load on demand when the signal matches.

| Signal | Reference | Content | |--------|-----------|---------| | Full cleanup workflow (9 categories) | `references/code-cleanup.md` | 3-phase cleanup: SCOPE, SCAN, REPORT | | Language-specific scan commands | `references/cleanup-scan-commands.md` | Per-language commands and expected output | | Cleanup report formatting | `references/cleanup-report-template.md` | Structured report template | | Ruff rules, F401/E711/B006 | `references/ruff-rules-reference.md` | Ruff rule reference by category | | Biome rules, ESLint migration | `references/biome-rules-reference.md` | Biome rule reference by category | | Python quality tool commands | `references/python-tool-commands.md` | Detailed tool command options | | Python quality report | `references/python-report-template.md` | Struct