python-quality-gate

# Python Quality Gate Skill

Run four quality tools in deterministic order -- ruff, pytest, mypy, bandit -- and produce a structured pass/fail report with severity-categorized issues and auto-fix commands.

## Reference Loading Table

| Signal | Load These Files | Why |
|---|---|---|
| writing the quality gate report | `report-template.md` | Loads detailed guidance from `report-template.md`. |
| invoking ruff/mypy/pytest; severity classification and pass/fail thresholds | `tool-commands.md` | Loads detailed guidance from `tool-commands.md`. |

## Instructions

### Phase 1: Detection and Setup

**Step 1: Read CLAUDE.md and detect project configuration.**

Read and follow the repository's CLAUDE.md before any execution. Then detect project configuration:

```bash
ls -la pyproject.toml setup.py setup.cfg mypy.ini .python-version 2>/dev/null
```

Identify Python version target, ruff config, pytest config, mypy config from pyproject.toml. Only validate code -- never add tools, features, or flexibility not requested.

**Step 2: Detect source and test directories.**

```bash
ls -d src/ app/ lib/ 2>/dev/null || echo "Source: current directory"
ls -d tests/ test/ 2>/dev/null || echo "Tests: not found"
```

**Step 3: Verify tool availability.**

```bash
ruff --version
pytest --version
mypy --version || echo "mypy not installed (optional)"
bandit --version || echo "bandit not installed (optional)"
```

If ruff or pytest are missing, STOP. These are required:
```
ERROR: Required tool not found: {tool_name}
Install with: pip install ruff pytest pytest-cov
```

Do not install missing tools automatically unless the user explicitly requests it. Do not modify pyproject.toml or configuration files unless explicitly asked.

**Gate**: ruff and pytest available. Project structure identified. Proceed only when gate passes.

### Phase 2: Execute Quality Checks

Run all checks in fixed order, capturing full output for each. Show complete command output with exact file paths and line numbers -- never summarize or paraphrase tool output, because summarization hides the details engineers need to locate and fix issues.

**Step 1: Ruff linting.**

```bash
ruff check . --output-format=grouped
```

**Step 2: Ruff formatting check.**

```bash
ruff format --check .
```

**Step 3: Type checking with mypy** (if installed).

```bash
mypy . --ignore-missing-imports --show-error-codes
```

Skip and note in report if mypy is not installed. Even if tests pass, still run mypy when available -- tests check behavior while types check contracts, and passing one does not make the other redundant.

**Step 4: Run test suite.**

```bash
pytest -v --tb=short --cov=src --cov-report=term-missing
```

If no tests directory exists, skip and note in report. Never skip tests to make the gate pass -- tests verify functionality, and skipping them hides broken code. Only skip optional tools (mypy, bandit) if genuinely unavailable, not to manufacture a passing status.

**Step 5: Security scanning with bandit** (if installed).

```bash
bandit -r src/ -ll --format=screen
```

Skip and note in report if bandit is not installed. Linting passing does not mean code is correct -- linting finds style issues, not logic or security bugs. Run every available tool.

**Gate**: All available tools have been run. Full output captured. Proceed to analysis.

### Phase 3: Categorize and Analyze

**Step 1: Categorize issues by severity.**

See `references/tool-commands.md` for complete severity classification tables.

Summary of severity levels:
- **Critical**: F errors (pyflakes), E9xx (syntax), undefined names, test failures, high-severity security
- **High**: E501, E711/E712, F841, N8xx, arg-type/assignment mypy errors
- **Medium**: W warnings, C4xx, no-untyped-def mypy errors
- **Low**: SIM suggestions, UP upgrade suggestions

Always prioritize critical issues over style fixes -- critical issues (F errors, test failures) break functionality while style issues do not. Fix critical first, high second; use auto-fix for bulk style cleanup only after critical issues are resolved.

**Step 2: Count auto-fixable issues.**

```bash
ruff check . --statistics
```

Issues marked with `[*]` are auto-fixable. Show suggested auto-fix commands for these issues so users know what can be fixed automatically.

**Step 3: Determine overall status.**

FAIL if:
- Any ruff F errors or test failures
- Any high-severity bandit issues
- Mypy errors exceed 10 (configurable)
- Test coverage below 80% (if coverage enabled)

PASS otherwise. Exit with non-zero status if any critical check fails.

**Gate**: All issues categorized. Pass/fail determined. Proceed to report.

### Phase 4: Generate Report

Format a structured markdown report. See `references/report-template.md` for the full template.

The report MUST include:
1. Overall PASS/FAIL status
2. Summary table (each tool's status and issue count)
3. Total issues and auto-fixable count
4. Detailed results per tool (issues grouped by severity, then grouped by type and file for readability)
5. Critical issues requiring attention with file:line references
6. Auto-fix commands section
7. Quality metrics: error counts and coverage percentages

Report facts -- show raw command output rather than describing it. No self-congratulation ("great job", "looking good"). Generate the full report even when only style issues are found, because style issues can hide real problems in noise and a full severity-prioritized report surfaces them.

Print the complete report to stdout. Never summarize or truncate. If `--output {file}` flag was provided, also write report to file. Remove any intermediate temporary files at completion -- keep the final report only if the user requested file output.

**Gate**: Report generated and displayed. Task complete.

### Auto-Fix Mode (only when explicitly requested)

Auto-fix modifies files in place -- never run it without explicit user confirmation. Running `ruff --fix` blindly can change code semantics (import removal, r