Quality Gates

Overview

Project-agnostic bash script enforcing Python code quality gates using pyrefly, radon, hypothesis, pytest, and markdownlint. Three execution modes provide flexibility for different workflows: unit-tests for fast feedback, all-tests for comprehensive pre-merge validation, no-tests for static analysis only. Coverage runs are excluded by default; run coverage only when the user explicitly requests it.

When to Use

Before committing Python code to enforce consistent quality checks across projects without directory structure assumptions.

Modes

Mode	Gates Run	Use Case
unit-tests	pyrefly, radon, hypothesis checks, pytest (unit/), markdownlint	Fast feedback during development
all-tests	pyrefly, radon, hypothesis checks, pytest (unit/ + integration/), markdownlint	Pre-merge/deploy comprehensive check
no-tests	pyrefly, radon, hypothesis checks, markdownlint	Static analysis only (time critical)

Quick Start

Running quality gates:

Make sure uv is installed.

# Fast feedback: lint + type check + unit tests
.claude/skills/quality-gates/scripts/quality-gates.sh unit-tests

# Pre-merge: everything including integration tests
.claude/skills/quality-gates/scripts/quality-gates.sh all-tests

# Quick static checks only
.claude/skills/quality-gates/scripts/quality-gates.sh no-tests

Implementation Details

• Script: scripts/quality-gates.sh - Uses uv/uvx for tool management
• Excluded directories: tests, test, docs, doc, examples, scripts, build, dist, .venv, venv, .tox, .git, node_modules, pycache, *.egg-info
• Graceful fallbacks: Skips missing tools without failing

Common Anti-Patterns

Rationalization	Reality
"Time-critical, skip checks"	Use no-tests mode for fast static validation
"Already tested manually"	Automation catches edge cases manual testing misses
"Partial checks sufficient"	Modes provide full coverage options; incomplete coverage misses bugs
"Coverage by default"	Coverage pollutes context; run it only when explicitly requested
"Too slow"	Tools are fast; skipping misses complexity and type issues
"Script not in project"	Copy to project to .claude/; run locally
"Tools not installed"	Install uv; graceful fallbacks skip missing tools

Red Flags

Stop and re-evaluate if you're:

• Skipping all checks
• "This time is different"
• "Good enough for now"
• Rationalizing under deadline pressure
• Adding coverage without an explicit request

All of these suggest running the script with the appropriate mode.