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.
bashpython3 ~/.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 | Structured report template |
| pyproject.toml template | references/pyproject-template.toml | Tool configuration template |
