---
name: python-review
description: "Python 3.13+ code review with mypy strict and ruff. Use when: user asks to review Python code, check types, lint, fix type errors, review pull request, code quality check, mypy errors, ruff violations, optimize Python, улучши код, ревью кода, проверь типы, код ревью питон, исправь mypy, исправь ruff."
argument-hint: "File or folder to review (e.g. src/module.py or src/)"
---

# Python Code Review (3.13+ · mypy strict · ruff)

Two-phase workflow: first **propose** improvements, then **apply** only what the user accepts.

## When to Use

- Review Python files before commit or PR
- Fix mypy strict or ruff violations
- Optimize performance, readability, or architecture
- Prepare code for Python 3.13+ compatibility

## Procedure

### Step 1 — Discover Project Config

Before running any tool, check if `pyproject.toml` exists in the workspace root.

Read it and extract:
- `[tool.mypy]` — use these settings instead of defaults; if `strict = true` is absent, treat it as enabled anyway
- `[tool.ruff]` and `[tool.ruff.lint]` — use `select`, `ignore`, `line-length`, `target-version`
- `[project]` → `requires-python` — confirm target is 3.13+

If `pyproject.toml` is absent — use the baseline config from
[references/default-config.md](./references/default-config.md).

### Step 2 — Run Static Analysis

Run both tools on the target file(s) and collect all findings:

```bash
# mypy
mypy --strict <target>

# ruff (check only, no fixes yet)
ruff check <target>
```

Also read the source file(s) to perform a manual review pass.

### Step 3 — Categorize Findings

Group all findings into three tiers (see full criteria in
[references/review-checklist.md](./references/review-checklist.md)):

| Tier | Label | Examples |
|------|-------|---------|
| 🔴 Must fix | Correctness / type safety | mypy errors, `Any` leaks, logic bugs, security issues |
| 🟡 Should fix | Code quality | ruff warnings, missing return types, dead code, mutable defaults |
| 🟢 Consider | Optimization / style | performance hints, readability, modern Python 3.13+ idioms |

### Step 4 — Present Proposals (DO NOT EDIT YET)

Output a structured review report:

```
## Code Review: <filename>

### 🔴 Must Fix ({N})
1. **[MYPY/RUFF code]** `symbol` — explanation
   ```python
   # before
   # after
   ```

### 🟡 Should Fix ({N})
...

### 🟢 Consider ({N})
...

---
Accept all fixes? Or specify which tiers/items to apply: "apply 🔴", "apply all", "apply 1,3,5"
```

**Do not modify any files until the user explicitly accepts.**

### Step 5 — Apply Accepted Fixes

Wait for the user's response. Parse their intent:

| User says | Action |
|-----------|--------|
| "apply all" / "применить всё" | Apply all tiers |
| "apply 🔴" / "применить красные" | Apply Must Fix only |
| "apply 🔴🟡" | Apply Must Fix + Should Fix |
| "apply 1,3,5" / "пункты 1,3,5" | Apply specific numbered items |
| "skip" / "отмена" | Do nothing |

Apply fixes following the rules in [references/fix-rules.md](./references/fix-rules.md).

After applying:
1. Re-run `mypy --strict` and `ruff check` to confirm zero remaining violations
2. Report: "Applied N fixes. Remaining issues: X" (or "Clean ✅")

### Step 6 — Final Check

If any 🔴 items were skipped — warn the user:
> ⚠️ {N} critical issue(s) not applied. The code may have type errors or bugs at runtime.