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