Review Python
Python review that covers what ruff and a type checker cannot decide for you — how state is
modeled, whether parsed data stays parsed, whether an exception hierarchy tells callers
anything, whether async work has an owner, and whether a good primitive is being bypassed.
Run on .py / .pyi files. Complements review-cleancode (SOLID/DRY/smells) — don't repeat it.
Review grading
Use only these finding priorities, in descending order:
- Critical Issues (Must Fix): a verified path causes data loss, a security failure, a materially
wrong operation, or makes a core workflow unusable without reasonable recovery.
- Improvements (Should Fix): an ordinary supported workflow demonstrably fails or repeatedly
imposes substantial friction, or a concrete design defect creates meaningful maintenance cost.
- Suggestions (Nice to Have): a worthwhile improvement with small practical impact, including
optional polish, local simplification, and rare recoverable edge cases.
Grade the demonstrated consequence, realistic reachability, and available recovery against project
priorities. A category, missing convention, hypothetical future problem, or confidence that a claim
is true does not set its priority. Do not assign automatic severity floors or ceilings. Keep
unverified claims in validation gaps, outside the graded finding count; distinguish suggestions
from defects. For plans, trace the consequence if implemented and state the assumptions.
Use the short labels Must Fix, Should Fix, and Nice to Have in summaries and ledgers.
Keep effort, verification status, user-facing change size, and tool/vendor diagnostic ratings
separate. When called by code-review, return its requested evidence and impact fields; the parent
owns scoring and final triage. Otherwise apply this rubric directly. Omit empty priority sections.
Relationship to the toolchain (read first)
Ruff's defaults changed radically in 0.16.0 and most "what ruff covers" intuition predates it:
"Ruff now enables a much larger set of rules by default (413, up from 59)."
— https://astral.sh/blog/ruff-v0.16.0
The trap: select replaces the default set; extend-select adds to it. A project with a
hand-written select = [...] is usually running fewer rules than an unconfigured ruff check.
So you cannot infer coverage from "they configured ruff" in either direction — read the config.
Step 0 is a baseline read, not a code read
Open pyproject.toml (or ruff.toml / setup.cfg / mypy.ini) and record:
| Check |
Why it changes your review |
select vs extend-select |
With select, diff their prefixes against the 413 defaults. Commonly lost: all 10 DTZ (naive datetime), all 10 ASYNC, TRY, LOG, G, TC, PIE, PERF. |
Is the whole B prefix selected? |
B904 (raise-without-from) is off by default and its tryceratops twin TRY200 was removed from ruff in v0.2.0. If B is absent, nothing checks exception chaining — then chaining is yours to review. |
S / BLE / SLF / ANN |
Only 3 of 73 S rules are on by default; SLF, ARG, ANN, ERA, FBT, EM, TID are entirely off. |
mypy strict, or check_untyped_defs |
"By default the bodies of functions without annotations are not type checked." Under plain mypy, an unannotated def is a hole in the checker's coverage, not a style nit — treat missing annotations as a visibility finding. |
pytest --strict-markers, filterwarnings, asyncio_mode |
In pytest-asyncio's default strict mode an async def test with no marker is collected and silently never awaited. It passes without running. |
Read this to know what to stay quiet about, not to report it. Recommending a lint or type
configuration is a project-level action — see §P — and belongs in an --all audit. On a diff
review the baseline has one job: stop you raising something a rule already covers.
What this skill checks
Python codebases go wrong the same handful of ways, over and over. So the default review looks
only at what the diff introduces — a new dict where a dataclass belongs, a new bare except, a
new subprocess without a timeout, a new write that bypasses the repo's atomic writer. Repo-wide
properties (is ruff configured with select or extend-select, is mypy strict, does pytest run
with --strict-markers) belong to §P, which runs at --all and nowhere else.
Usage
/review-python # Review context-related code
/review-python --staged # Review staged changes
/review-python --unpushed # Review files changed across all unpushed commits
/review-python --changed # Review unstaged changes
/review-python --all # Full codebase audit (parallel agents)
/review-python --multi # Also get external advisor opinions
Scope
| Flag |
Scope |
Method |
| (none) |
Context-related code |
Files from the current conversation context. If no context, ask the user to specify files or use --staged/--changed/--all. |
--staged |
Staged changes |
git diff --cached --name-only |
--unpushed |
Files changed across unpushed commits |
git diff --name-only $(git rev-list HEAD --not --remotes | tail -1)^..HEAD |
--changed |
Unstaged changes |
git diff --name-only |
--all |
Full codebase + §P project-level checks |
Glob *.py/*.pyi, parallel agents |
--multi |
Add external opinions |
Combines with any scope above; invokes second-opinion --quick |
--unpushed derives its range from git rev-list HEAD --not --remotes (oldest unpushed commit's
parent → HEAD). If nothing is unpushed, or there is no remote/upstream (or the range walks back to
the root commit) so it can't be determined reliably, stop and ask the user to pick another scope.
Restrict the resolved file list to Python extensions before reviewing.
Workflow
Determine scope (see table) and filter to Python files only.
Read the baseline (Step 0 above) — before reading any code.
Identify the project shape — CLI, library, backend, or data/script. §5 changes by shape,
and a finding that is right for a library is often wrong for a CLI.
Read AGENTS.md / CLAUDE.md in the repo root for project conventions.
Review each file against §1–§6 — against what the diff introduces. Add §P only at
--all. Load references/async.md when the code touches asyncio, threads or a TUI event loop;
load references/boundaries.md when it touches subprocess, the filesystem, or parsing external
input.
Parallelize if scope has >5 files: one sub-agent per category, merge and dedupe.
External opinions (if --multi): invoke second-opinion --quick with this prompt:
Read-only Python review. Assume ruff and mypy already handle mechanical rules — do NOT repeat
lint-level findings (mutable defaults, naive datetimes, late-binding closures, bare excepts,
unsorted imports). Focus on DESIGN judgment: is data that was validated at the perimeter
re-widened to dict[str, Any] so every consumer re-validates or forgets to? Are correlated
fields modeled as a bag of optionals where a Literal-discriminated union plus match plus
assert_never belongs? Does the exception hierarchy correspond to distinct caller responses, or
is it bypassed by raw ValueError? Does every async task have an owner that awaits it, and does
cancellation propagate? Is a good existing primitive (atomic write, lock, coercion helper)
bypassed by some call sites? 300 words or less.
Wait for all external results before proceeding.
Classify severity and report, grouped by severity.
1. Data & state modeling
The core value, and usually the root of findings in §2 and §3. A type checker checks that types
are consistent; only a human checks that they are right.
- A
dict standing in for a domain record. The tell is the same field read as t["x"] in
some places and t.get("x") in others — each call site independently guessing at optionality.
Second tell: the schema exists only inside one constructor, and other code paths add keys that
constructor never mentions, so the shape is genuinely open. Recommend a TypedDict (for a dict
you were handed) or a dataclass (for a thing you constructed).
- Validated at the perimeter, then re-widened. A schema validator proves exact shapes and
hands back
dict[str, Any]; the type system learns nothing, so interior code either re-checks
the same invariants in branches that can never execute, or forgets to and trusts a value nobody
proved. Both are the same defect. "Push the burden of proof upward as far as possible, but no
further… Get your data into the most precise representation you need as quickly as you can."
(Parse, don't validate — https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/)
- A declared enum that isn't enforced. A JSON schema with
"enum": [...] sent to an external
service (an LLM, an API) is a request, not a guarantee. If the response string is written into
the domain unchecked, an unexpected value silently matches no branch anywhere and the record
vanishes from every rollup with no error. Recommend a Literal on the setter plus one perimeter
check.
- Bag-of-optionals where a tagged union belongs. Fields correlated by convention —
"
claim is non-None exactly when status != "busy"" — force a guard at every use, and the
guard usually raises an internal error for a state the code constructs itself. A string like
"internal: ..." in a raise message is the author flagging an unrepresentable state. Recommend
a Literal discriminator + match + assert_never, which converts the impossible branch from
a runtime raise into a type error. "The type checker will allow this call only if it can prove
that the code is not reachable." (https://typing.python.org/en/latest/guides/unreachable.html)
- An enum decomposed back into mutually-exclusive booleans. Four independent bools for five
legal states is 16 representable states, and the exclusivity gets reassembled by an
elif chain
in the renderer. Keep the enum and switch on it.
- In-band sentinels —
"", -1, or 0 overloaded to mean "none"/"not applicable", so a
typo in a magic string is a silent no-op. Especially where a str field carries three values
and one of them is emptiness.
- Positional construction from parsed data —
Record(*fields) splatting a row of same-typed
strings. Reordering the dataclass silently mis-assigns every persisted record and nothing
type-checks it. Also flag the asymmetry where the encoder spells all fields out and the decoder
splats, since the two halves can drift.
- Tuples with a comment instead of a
NamedTuple — list fields whose element shape lives in
a trailing comment and is then indexed positionally.
frozen= as a decision, not a habit. Ask whether the object is ever a dict key or set
member: "If eq is true and frozen is false, __hash__() will be set to None, marking it
unhashable." And __eq__ without __hash__ (PLW1641, off by default) breaks the invariant
that equal objects hash equally.
- Structural conformance faked with alias properties — a class growing a field that is always
None, or aliasing another field, so two types can be indexed uniformly. That is a union
wanting to be written down.
2. Typing judgment
- Unannotated defs and
args: Any are coverage holes. Under non-strict mypy the body of an
unannotated function is unchecked entirely. args: Any on a CLI command function switches
strict mode off at the busiest boundary in the program — and the cost shows up in the tests,
which must fabricate the contract by hand (Namespace(...) objects that nothing verifies).
Report the hole, not the missing annotation.
Any laundering into a Literal. A value from json.loads or a dict[str, Any] satisfies
a Literal[...] parameter with no check. Related: a cast(Literal[...], x) that is correct only
because an argparse choices= tuple elsewhere happens to match — two unlinked copies of one
enumeration.
@runtime_checkable Protocol isinstance is not validation. "act as simple-minded runtime
protocols that check only the presence of given attributes, ignoring their type signatures."
Flag code that treats it as a guarantee about the signature.
- Variance: accept wide, return narrow.
list[Shape] as a parameter rejects a list[Triangle]
because list is invariant; Sequence[Shape] accepts it. Take Iterable/Sequence/Mapping
in, return the concrete type. Flag list[X] demanded for read-only iteration.
Any vs object vs Never — object keeps checking and forces narrowing; Any disables
it. Never is the bottom type and is what makes assert_never work.
Self for fluent APIs, alternative constructors and __enter__; @override (PEP 698)
to catch a base-class rename that leaves the subclass orphaned — no ruff rule covers it.
@final has no runtime effect — flag code relying on it for safety rather than for the
checker.
3. Error modeling
- A hierarchy that exists and is bypassed. The highest-value finding in this section. A
project defines
AppError(exit_code, is_error) with meaningful subclasses, then raises raw
ValueError from dozens of sites — sometimes in the same function as a correct raise. Every
distinction the hierarchy exists to carry is discarded at the top-level handler.
- An exception that escapes the top-level handler. Check what the entry point actually
catches against what the code actually raises. A bare
RuntimeError matches neither
except AppError nor except (DomainError, ValueError) even when AppError subclasses
RuntimeError — subclass relationships run the wrong way for this.
- A catch so broad it flattens the hierarchy.
except (FileNotFoundError, OSError, ValueError, RuntimeError) catches the entire domain when the domain's base is RuntimeError, collapses
every exit code to 1, and drops a deliberate exit 0.
- Cross-function exception flow. A module's
discover() guards json.JSONDecodeError and its
parse() doesn't, while the caller catches only OSError. JSONDecodeError and
UnicodeDecodeError are both ValueError, not OSError — one corrupt input file kills the
whole scan. This needs reading two functions and the caller; no rule reaches it.
- A builtin IO exception used as a domain signal, then caught too broadly —
raise FileNotFoundError("no config here") caught by an except FileNotFoundError that also swallows
a genuinely missing binary and reports success.
- Result-or-error smuggled in-band —
-> RunResult | str where str means failure, or
-> tuple[str | None, int | None]. Nothing forces a new caller to check. Recommend a failure
dataclass or an exception.
- Computed diagnostics discarded — a
skipped counter incremented and never returned, so the
user is told "deleting 4" with no sign the 5th was silently retained. F841 stays quiet because
+= counts as a read.
- A handler that catches but does nothing. Detection of a blind
except is BLE001/E722;
whether the handler is the bug is yours. Distinguish "genuinely don't care" from "lost the
diagnostic". contextlib.suppress spanning ten statements suppresses far more than the one
call it was written for — "should be used only to cover very specific errors where silently
continuing with program execution is known to be the right thing to do."
- Chaining, only if
B904 is not reachable per Step 0.
4. Async, concurrency & boundaries
Load references/async.md when the code touches asyncio, threads or a TUI event loop, and
references/boundaries.md for subprocess, filesystem and untrusted input. The two headline
items, because they recur everywhere:
- Blocking work reachable from the event loop indirectly. Ruff's
ASYNC22x rules are
call-site-local: they flag a literal subprocess.run inside an async def, not a named function
three frames above one. An async handler that calls something which scans a filesystem, sleeps,
and shells out is invisible to them and freezes the UI completely.
- A good primitive that call sites bypass. Find the repo's best existing atomic-write, lock,
or coercion helper, then check who doesn't use it. Divergent copies of the same primitive with
different safety guarantees — only one of which
fsyncs — are a real and common defect.
5. Project shape
A finding that is right for a library is often wrong for a CLI. Establish the shape first.
| Shape |
What changes |
| CLI |
Exit codes: subprocess.call returns a negative value for a signal-terminated child, so passing it to sys.exit turns Ctrl-C into shell status 254. Results to stdout, diagnostics to stderr, so pipelines work. input() without an EOFError guard crashes under < /dev/null and in CI. Interactive prompts belong at the CLI edge, not in the library layer where every caller must arrange a TTY. print is correct here — never flag T201. |
| Library |
__all__ is the typed-API contract, not decoration: "Imported symbols are considered private by default", and import X as X / from Y import X as X are what re-export. Flag a py.typed package with neither. Add NullHandler and never configure logging — "the configuration of handlers is the prerogative of the application developer who uses your library." Never call sys.exit; raise. No import-time side effects. Variance is caller compatibility, so §2's accept-wide/return-narrow is a compatibility rule, not a style one. |
| Backend |
The bug is the third combination: an async def handler containing blocking I/O — worse than either pure option, since FastAPI runs a plain def handler in a threadpool. Django: SynchronousOnlyOperation from ORM calls under a running loop, the a-prefixed queryset variants, and N+1 via missing select_related/prefetch_related. Plus request-scoped state parked in module globals, and missing timeouts on outbound calls. |
| Data / scripts |
Reproducible seeds; float and NaN handling (math.isclose needs a positive abs_tol to compare against zero at all, and NaN is never close to anything including itself); chunked reads over read(). Where a hand-written table of examples guards a real invariant, recommend hypothesis. |
6. Test quality
Module-level state and import-time side effects are in references/boundaries.md §8 — they
belong to the same review pass as the other boundary items. What follows is tests.
- Asserting private state instead of rendered behaviour —
app._inbox, app._active_tab.
A change that correctly updates the list but fails to render it still passes.
- Fixed-iteration event-loop pumps as a worker wait —
for _ in range(5): await pilot.pause(),
with the number varying across tests. Every such test is timing-dependent by construction;
recommend the framework's real wait (workers.wait_for_complete).
- Monkeypatching private internals, and the double-patch tell — the same name patched in two
modules because
from X import y creates a second binding. A third importer silently gets the
real function and the stub quietly stops covering it, with no failure.
- Tests fabricating an untyped contract — hand-built
Namespace(...) objects standing in for
a real parser; a downstream cost of §2's args: Any.
- Negative assertions that pin nothing —
assert "Metro" not in text passes for every wrong
renderer that happens not to print that word. Keep the ones naming a specific thing that would
otherwise have happened (assert not path.exists() after a delete, assert secret not in err).
P. Project-level checks — --all only
Repo-wide configuration. It changes rarely, so raising it on a diff review is noise.
- ruff
select vs extend-select. select replaces the 413-rule default set, so a project
with a hand-written select is usually running fewer rules than an unconfigured ruff check.
Diff the prefixes against the defaults and report what's lost — commonly all 10 DTZ (naive
datetime), all 10 ASYNC, plus TRY, LOG, G, TC, PIE, PERF. Recommending
extend-select fixes the whole category at once. Note that 18 opinionated E/F rules were
removed from the 0.16 default set (E401, E402, E701–E703, E711–E714, E721,
E731, E741–E743, F403, F405, F406, F722), so a repo selecting bare E/F must
keep those listed explicitly to retain them.
- mypy strictness. Plain mypy does not check the bodies of unannotated functions at all. Where
a codebase has many partially-annotated defs, stage it:
check_untyped_defs, then
disallow_incomplete_defs, then strict.
- pytest configuration —
--strict-markers, --strict-config, filterwarnings = ["error"],
a coverage threshold, and whether asyncio_mode matches how the tests are actually marked.
- Whether the repo has a good primitive that call sites bypass — atomic write, lock, coercion
helper. Finding the divergent copies is a whole-repo sweep; a diff review only checks whether
this change bypassed it.
- Encoding discipline across all readers, which is only visible in aggregate.
Do NOT flag these
- Anything in §P, on a diff review. Lint and type configuration are project properties; this
diff did not change them.
Already mechanical, or wrong. Check Step 0 before suppressing — if the project's config doesn't
reach the rule, fold it into the one-time recommendation instead of reporting each occurrence.
- Mutable default arguments (
B006), function calls in defaults (B008), mutable class
defaults (RUF012) — and the dataclass decorator raises on them anyway.
- Late-binding closures in loops (
B023), lru_cache on methods (B019).
- Naive datetimes — all ten
DTZ rules are on by default. The best-covered category ruff has.
- Blind
except detection (BLE001, E722) — the judgment of whether the handler does
anything useful stays yours.
- PEP 695 generic syntax (
UP046, UP047), import sorting (I001), modern-syntax rewrites
(UP).
print in a CLI — see §5.
- Demanding Pydantic. A stdlib dataclass plus a perimeter validator is a complete answer; a
validation library is a dependency decision, not a review finding.
- Demanding
ty. It is 0.0.x with no API stability commitment. pyrefly is production-ready
if mypy's speed is a real problem — but mypy --strict is not a finding to begin with.
- Docstring coverage (
D) unless the project already enforces it.
Output Format
## Python Review: {scope}
### Baseline
{Project shape, and whether `B904` is reachable (it decides whether exception chaining is yours to
review). **At `--all` only:** the §P results. On a diff review, omit this block unless something in
it changes what you reported.}
### Critical Issues (Must Fix)
- {file}:{line} — {category}: {description}
**Why it's not a ruff or mypy finding:** {what judgment this needed}
**Impact:** {what breaks}
**Fix:** {model change / boundary validation / real failure path — with code}
### Improvements (Should Fix)
- {file}:{line} — {category}: {description}
**Fix:** {solution}
### Suggestions (Nice to Have)
- {file}:{line} — {category}: {description} — {suggested change}
If --multi was used, append one subsection per advisor that responded (titled with the advisor's
name as reported by second-opinion), then a Cross-Model Agreement subsection.
Examples
Validated data re-widened:
/review-python --staged
A 400-line schema validator proves the exact shape of each resource spec, then stores the result
as dict[str, Any]. Downstream, provision() re-checks isinstance(spec.get("range"), list) and
raises on an unknown type — branches that cannot execute, and which permanently depress the
coverage number. Reports Nice to Have on those facts; Should Fix needs demonstrated meaningful
maintenance cost or a failing supported path. A TypedDict union keyed on a Literal type field turns the
final else into an assert_never type error and deletes five defensive raises. Not a mypy
finding: Any conforms to every consumer, so mypy has no discriminator to narrow on and cannot
see the branches as unreachable.
Blocking the event loop indirectly:
/review-python --changed
An async worker pushes a progress modal, then calls cmd_roundup(...), which three frames down
scans every session directory, calls time.sleep, runs shutil.rmtree, and issues N sequential
LLM subprocesses with no timeout=. Reports Should Fix — the modal cannot paint and keystrokes are dead
until it returns; fix with asyncio.to_thread or thread=True, and add a timeout. ASYNC221 is
silent because the subprocess call is not lexically inside the async def.
Hierarchy bypassed:
/review-python
errors.py defines ApplicationError(exit_code, is_error) with UsageError (exit 2) and
MissingRecipeError (exit 0). The code raises 61 raw ValueErrors, four of them in a function
that raises UsageError correctly on the line above. Reports Should Fix — every one renders identically
through the generic handler and exits 1, discarding the distinctions the hierarchy exists to carry.
TRY002 only catches raise Exception; ValueError is a perfectly ordinary raise.
Troubleshooting
Findings overlap with ruff or mypy
Solution: Check Step 0 — whether the project's config actually reaches that rule. Ruff's
defaults are large but select replaces them, so coverage is not inferable from the presence of a
config. If the rule runs, drop the finding. If it doesn't, fold it into the one-time baseline
recommendation rather than reporting each occurrence.
Can't tell whether a dict should be a dataclass
Solution: Ask where it was born. Handed to you by json.loads, a subprocess, or a wire format
and passed straight through → TypedDict describes it honestly. Constructed by your own code, or
carrying invariants across function boundaries → a dataclass, validated once at construction. The
deciding tell is whether any consumer has to ask "is this key present?" about a field the
producer always sets.
Can't tell whether a broad except is wrong
Solution: Read what the handler does, not what it catches. Re-raising as a domain error, or
logging with the traceback and continuing a loop that must not die, is fine. Returning None to a
caller that cannot distinguish "absent" from "failed" is not. And check the callers — a handler
can be correct while the caller's own except clause fails to match what actually propagates.
Notes
- Model first, parse second, annotate third. Most
Any and most defensive re-validation dissolve
once the underlying data is modeled correctly.
- Respect project conventions in AGENTS.md / CLAUDE.md — a codebase may deliberately use plain
dicts at a boundary, or standardize on returning
Result-shaped tuples.
- Don't be dogmatic:
TypedDict migrations, wrapper types, and exhaustive match all have costs.
Recommend them where they prevent real bugs, not everywhere they are possible.
- Test code: patching your own module's private helper in a focused unit test is defensible;
patching a name in two places because of import bindings, or asserting on private attributes
instead of rendered output, is not. Also flag
sleep-based synchronization and real clock,
network, or home-directory access in unit tests.
- Sources: the ruff 0.16 release notes and rule documentation (astral.sh); the CPython
asyncio, dataclasses, enum, contextlib, subprocess and logging docs; the typing spec
and guides at typing.python.org (exhaustiveness, distributing, re-export); PEP 654 and PEP 698;
Alexis King, "Parse, don't validate"; Hynek Schlawack on hashes and equality; mypy's command-line
reference. ruff and the type checker own the mechanical rules referenced above.
1---2name: review-python3description: Python-specific code review focused on JUDGMENT-level design a linter and type checker can't decide — modeling state so invalid combinations are unrepresentable, keeping parsed data parsed instead of re-widening it to dicts, exception hierarchies that callers can act on, async task lifetime and cancellation, and boundary discipline for subprocess, filesystem and untrusted input. Deliberately does NOT duplicate ruff or mypy. Auto-invoked by `code-review` on Python projects. Triggers "review python", "python review", "asyncio review", "type modeling review".4argument-hint: '[--staged | --unpushed | --changed | --all | --multi]'5effort: high6metadata:7 source: https://skillmd.com/skills/nielsmadan/review-python8---910<!-- Generated from https://github.com/nielsmadan/agentic-coding — edits here are overwritten. -->1112# Review Python1314Python review that covers what **ruff and a type checker cannot decide for you** — how state is15*modeled*, whether parsed data stays parsed, whether an exception hierarchy tells callers16anything, whether async work has an owner, and whether a good primitive is being bypassed.1718Run on `.py` / `.pyi` files. Complements `review-cleancode` (SOLID/DRY/smells) — don't repeat it.1920## Review grading2122Use only these finding priorities, in descending order:2324- **Critical Issues (Must Fix):** a verified path causes data loss, a security failure, a materially25 wrong operation, or makes a core workflow unusable without reasonable recovery.26- **Improvements (Should Fix):** an ordinary supported workflow demonstrably fails or repeatedly27 imposes substantial friction, or a concrete design defect creates meaningful maintenance cost.28- **Suggestions (Nice to Have):** a worthwhile improvement with small practical impact, including29 optional polish, local simplification, and rare recoverable edge cases.3031Grade the demonstrated consequence, realistic reachability, and available recovery against project32priorities. A category, missing convention, hypothetical future problem, or confidence that a claim33is true does not set its priority. Do not assign automatic severity floors or ceilings. Keep34unverified claims in validation gaps, outside the graded finding count; distinguish suggestions35from defects. For plans, trace the consequence if implemented and state the assumptions.3637Use the short labels **Must Fix**, **Should Fix**, and **Nice to Have** in summaries and ledgers.38Keep effort, verification status, user-facing change size, and tool/vendor diagnostic ratings39separate. When called by `code-review`, return its requested evidence and impact fields; the parent40owns scoring and final triage. Otherwise apply this rubric directly. Omit empty priority sections.4142## Relationship to the toolchain (read first)4344**Ruff's defaults changed radically in 0.16.0** and most "what ruff covers" intuition predates it:4546> "Ruff now enables a much larger set of rules by default (413, up from 59)."47> — <https://astral.sh/blog/ruff-v0.16.0>4849The trap: **`select` replaces the default set; `extend-select` adds to it.** A project with a50hand-written `select = [...]` is usually running *fewer* rules than an unconfigured `ruff check`.51So you cannot infer coverage from "they configured ruff" in either direction — read the config.5253### Step 0 is a baseline read, not a code read5455Open `pyproject.toml` (or `ruff.toml` / `setup.cfg` / `mypy.ini`) and record:5657| Check | Why it changes your review |58|---|---|59| `select` vs `extend-select` | With `select`, diff their prefixes against the 413 defaults. Commonly lost: all 10 `DTZ` (naive datetime), all 10 `ASYNC`, `TRY`, `LOG`, `G`, `TC`, `PIE`, `PERF`. |60| Is the whole `B` prefix selected? | `B904` (raise-without-from) is **off by default** and its tryceratops twin `TRY200` was *removed* from ruff in v0.2.0. If `B` is absent, **nothing** checks exception chaining — then chaining is yours to review. |61| `S` / `BLE` / `SLF` / `ANN` | Only 3 of 73 `S` rules are on by default; `SLF`, `ARG`, `ANN`, `ERA`, `FBT`, `EM`, `TID` are entirely off. |62| mypy `strict`, or `check_untyped_defs` | *"By default the bodies of functions without annotations are not type checked."* Under plain mypy, an unannotated `def` is a **hole in the checker's coverage**, not a style nit — treat missing annotations as a visibility finding. |63| pytest `--strict-markers`, `filterwarnings`, `asyncio_mode` | In pytest-asyncio's default **strict** mode an `async def` test with no marker is collected and silently never awaited. It passes without running. |6465**Read this to know what to stay quiet about, not to report it.** Recommending a lint or type66configuration is a *project-level* action — see §P — and belongs in an `--all` audit. On a diff67review the baseline has one job: stop you raising something a rule already covers.6869## What this skill checks7071**Python codebases go wrong the same handful of ways, over and over.** So the default review looks72only at what the diff introduces — a new `dict` where a dataclass belongs, a new bare `except`, a73new subprocess without a timeout, a new write that bypasses the repo's atomic writer. Repo-wide74properties (is ruff configured with `select` or `extend-select`, is mypy strict, does pytest run75with `--strict-markers`) belong to **§P**, which runs at `--all` and nowhere else.7677## Usage7879```80/review-python # Review context-related code81/review-python --staged # Review staged changes82/review-python --unpushed # Review files changed across all unpushed commits83/review-python --changed # Review unstaged changes84/review-python --all # Full codebase audit (parallel agents)85/review-python --multi # Also get external advisor opinions86```8788## Scope8990| Flag | Scope | Method |91|------|-------|--------|92| (none) | Context-related code | Files from the current conversation context. If no context, ask the user to specify files or use `--staged`/`--changed`/`--all`. |93| `--staged` | Staged changes | `git diff --cached --name-only` |94| `--unpushed` | Files changed across unpushed commits | `git diff --name-only $(git rev-list HEAD --not --remotes \| tail -1)^..HEAD` |95| `--changed` | Unstaged changes | `git diff --name-only` |96| `--all` | Full codebase + **§P project-level checks** | Glob `*.py`/`*.pyi`, parallel agents |97| `--multi` | Add external opinions | Combines with any scope above; invokes `second-opinion --quick` |9899`--unpushed` derives its range from `git rev-list HEAD --not --remotes` (oldest unpushed commit's100parent → HEAD). If nothing is unpushed, or there is no remote/upstream (or the range walks back to101the root commit) so it can't be determined reliably, stop and ask the user to pick another scope.102Restrict the resolved file list to Python extensions before reviewing.103104## Workflow1051061. **Determine scope** (see table) and filter to Python files only.1072. **Read the baseline** (Step 0 above) — before reading any code.1083. **Identify the project shape** — CLI, library, backend, or data/script. §5 changes by shape,109 and a finding that is right for a library is often wrong for a CLI.1104. **Read AGENTS.md / CLAUDE.md** in the repo root for project conventions.1115. **Review each file** against §1–§6 — against what the diff introduces. Add **§P only at112 `--all`**. Load `references/async.md` when the code touches asyncio, threads or a TUI event loop;113 load `references/boundaries.md` when it touches subprocess, the filesystem, or parsing external114 input.1156. **Parallelize** if scope has >5 files: one sub-agent per category, merge and dedupe.1167. **External opinions** (if `--multi`): invoke `second-opinion --quick` with this prompt:117118 ```119 Read-only Python review. Assume ruff and mypy already handle mechanical rules — do NOT repeat120 lint-level findings (mutable defaults, naive datetimes, late-binding closures, bare excepts,121 unsorted imports). Focus on DESIGN judgment: is data that was validated at the perimeter122 re-widened to dict[str, Any] so every consumer re-validates or forgets to? Are correlated123 fields modeled as a bag of optionals where a Literal-discriminated union plus match plus124 assert_never belongs? Does the exception hierarchy correspond to distinct caller responses, or125 is it bypassed by raw ValueError? Does every async task have an owner that awaits it, and does126 cancellation propagate? Is a good existing primitive (atomic write, lock, coercion helper)127 bypassed by some call sites? 300 words or less.128 ```129130 Wait for all external results before proceeding.1318. **Classify severity** and **report**, grouped by severity.132133## 1. Data & state modeling134135The core value, and usually the root of findings in §2 and §3. A type checker checks that types136are *consistent*; only a human checks that they are *right*.137138- **A `dict` standing in for a domain record.** The tell is the same field read as `t["x"]` in139 some places and `t.get("x")` in others — each call site independently guessing at optionality.140 Second tell: the schema exists only inside one constructor, and other code paths add keys that141 constructor never mentions, so the shape is genuinely open. Recommend a `TypedDict` (for a dict142 you were *handed*) or a dataclass (for a thing you *constructed*).143- **Validated at the perimeter, then re-widened.** A schema validator proves exact shapes and144 hands back `dict[str, Any]`; the type system learns nothing, so interior code either re-checks145 the same invariants in branches that can never execute, or forgets to and trusts a value nobody146 proved. Both are the same defect. *"Push the burden of proof upward as far as possible, but no147 further… Get your data into the most precise representation you need as quickly as you can."*148 (Parse, don't validate — <https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/>)149- **A declared enum that isn't enforced.** A JSON schema with `"enum": [...]` sent to an external150 service (an LLM, an API) is a *request*, not a guarantee. If the response string is written into151 the domain unchecked, an unexpected value silently matches no branch anywhere and the record152 vanishes from every rollup with no error. Recommend a `Literal` on the setter plus one perimeter153 check.154- **Bag-of-optionals where a tagged union belongs.** Fields correlated by convention —155 "`claim` is non-None exactly when `status != "busy"`" — force a guard at every use, and the156 guard usually raises an internal error for a state the code constructs itself. A string like157 `"internal: ..."` in a raise message is the author flagging an unrepresentable state. Recommend158 a `Literal` discriminator + `match` + `assert_never`, which converts the impossible branch from159 a runtime raise into a type error. *"The type checker will allow this call only if it can prove160 that the code is not reachable."* (<https://typing.python.org/en/latest/guides/unreachable.html>)161- **An enum decomposed back into mutually-exclusive booleans.** Four independent bools for five162 legal states is 16 representable states, and the exclusivity gets reassembled by an `elif` chain163 in the renderer. Keep the enum and switch on it.164- **In-band sentinels** — `""`, `-1`, or `0` overloaded to mean "none"/"not applicable", so a165 typo in a magic string is a silent no-op. Especially where a `str` field carries three values166 and one of them is emptiness.167- **Positional construction from parsed data** — `Record(*fields)` splatting a row of same-typed168 strings. Reordering the dataclass silently mis-assigns every persisted record and nothing169 type-checks it. Also flag the asymmetry where the encoder spells all fields out and the decoder170 splats, since the two halves can drift.171- **Tuples with a comment instead of a `NamedTuple`** — `list` fields whose element shape lives in172 a trailing comment and is then indexed positionally.173- **`frozen=` as a decision, not a habit.** Ask whether the object is ever a dict key or set174 member: *"If eq is true and frozen is false, `__hash__()` will be set to `None`, marking it175 unhashable."* And `__eq__` without `__hash__` (`PLW1641`, off by default) breaks the invariant176 that equal objects hash equally.177- **Structural conformance faked with alias properties** — a class growing a field that is always178 `None`, or aliasing another field, so two types can be indexed uniformly. That is a union179 wanting to be written down.180181## 2. Typing judgment182183- **Unannotated defs and `args: Any` are coverage holes.** Under non-strict mypy the body of an184 unannotated function is unchecked entirely. `args: Any` on a CLI command function switches185 strict mode off at the busiest boundary in the program — and the cost shows up in the tests,186 which must fabricate the contract by hand (`Namespace(...)` objects that nothing verifies).187 Report the *hole*, not the missing annotation.188- **`Any` laundering into a `Literal`.** A value from `json.loads` or a `dict[str, Any]` satisfies189 a `Literal[...]` parameter with no check. Related: a `cast(Literal[...], x)` that is correct only190 because an argparse `choices=` tuple elsewhere happens to match — two unlinked copies of one191 enumeration.192- **`@runtime_checkable` Protocol `isinstance` is not validation.** *"act as simple-minded runtime193 protocols that check only the presence of given attributes, ignoring their type signatures."*194 Flag code that treats it as a guarantee about the signature.195- **Variance: accept wide, return narrow.** `list[Shape]` as a parameter rejects a `list[Triangle]`196 because `list` is invariant; `Sequence[Shape]` accepts it. Take `Iterable`/`Sequence`/`Mapping`197 in, return the concrete type. Flag `list[X]` demanded for read-only iteration.198- **`Any` vs `object` vs `Never`** — `object` keeps checking and forces narrowing; `Any` disables199 it. `Never` is the bottom type and is what makes `assert_never` work.200- **`Self`** for fluent APIs, alternative constructors and `__enter__`; **`@override`** (PEP 698)201 to catch a base-class rename that leaves the subclass orphaned — no ruff rule covers it.202- **`@final` has no runtime effect** — flag code relying on it for safety rather than for the203 checker.204205## 3. Error modeling206207- **A hierarchy that exists and is bypassed.** The highest-value finding in this section. A208 project defines `AppError(exit_code, is_error)` with meaningful subclasses, then raises raw209 `ValueError` from dozens of sites — sometimes in the same function as a correct raise. Every210 distinction the hierarchy exists to carry is discarded at the top-level handler.211- **An exception that escapes the top-level handler.** Check what the entry point actually212 catches against what the code actually raises. A bare `RuntimeError` matches neither213 `except AppError` nor `except (DomainError, ValueError)` even when `AppError` subclasses214 `RuntimeError` — subclass relationships run the wrong way for this.215- **A catch so broad it flattens the hierarchy.** `except (FileNotFoundError, OSError, ValueError,216 RuntimeError)` catches the entire domain when the domain's base *is* `RuntimeError`, collapses217 every exit code to 1, and drops a deliberate exit 0.218- **Cross-function exception flow.** A module's `discover()` guards `json.JSONDecodeError` and its219 `parse()` doesn't, while the caller catches only `OSError`. `JSONDecodeError` and220 `UnicodeDecodeError` are both `ValueError`, not `OSError` — one corrupt input file kills the221 whole scan. This needs reading two functions and the caller; no rule reaches it.222- **A builtin IO exception used as a domain signal**, then caught too broadly — `raise223 FileNotFoundError("no config here")` caught by an `except FileNotFoundError` that also swallows224 a genuinely missing binary and reports success.225- **Result-or-error smuggled in-band** — `-> RunResult | str` where `str` means failure, or226 `-> tuple[str | None, int | None]`. Nothing forces a new caller to check. Recommend a failure227 dataclass or an exception.228- **Computed diagnostics discarded** — a `skipped` counter incremented and never returned, so the229 user is told "deleting 4" with no sign the 5th was silently retained. `F841` stays quiet because230 `+=` counts as a read.231- **A handler that catches but does nothing.** Detection of a blind `except` is `BLE001`/`E722`;232 whether the handler *is* the bug is yours. Distinguish "genuinely don't care" from "lost the233 diagnostic". `contextlib.suppress` spanning ten statements suppresses far more than the one234 call it was written for — *"should be used only to cover very specific errors where silently235 continuing with program execution is known to be the right thing to do."*236- **Chaining**, only if `B904` is not reachable per Step 0.237238## 4. Async, concurrency & boundaries239240**Load `references/async.md`** when the code touches asyncio, threads or a TUI event loop, and241**`references/boundaries.md`** for subprocess, filesystem and untrusted input. The two headline242items, because they recur everywhere:243244- **Blocking work reachable from the event loop *indirectly*.** Ruff's `ASYNC22x` rules are245 call-site-local: they flag a literal `subprocess.run` inside an `async def`, not a named function246 three frames above one. An `async` handler that calls something which scans a filesystem, sleeps,247 and shells out is invisible to them and freezes the UI completely.248- **A good primitive that call sites bypass.** Find the repo's best existing atomic-write, lock,249 or coercion helper, then check who doesn't use it. Divergent copies of the same primitive with250 different safety guarantees — only one of which `fsync`s — are a real and common defect.251252## 5. Project shape253254A finding that is right for a library is often wrong for a CLI. Establish the shape first.255256| Shape | What changes |257|---|---|258| **CLI** | Exit codes: `subprocess.call` returns a **negative** value for a signal-terminated child, so passing it to `sys.exit` turns Ctrl-C into shell status 254. Results to stdout, diagnostics to stderr, so pipelines work. `input()` without an `EOFError` guard crashes under `< /dev/null` and in CI. Interactive prompts belong at the CLI edge, not in the library layer where every caller must arrange a TTY. **`print` is correct here — never flag `T201`.** |259| **Library** | `__all__` is the typed-API contract, not decoration: *"Imported symbols are considered private by default"*, and `import X as X` / `from Y import X as X` are what re-export. Flag a `py.typed` package with neither. Add `NullHandler` and never configure logging — *"the configuration of handlers is the prerogative of the application developer who uses your library."* Never call `sys.exit`; raise. No import-time side effects. Variance is caller compatibility, so §2's accept-wide/return-narrow is a compatibility rule, not a style one. |260| **Backend** | The bug is the *third* combination: an `async def` handler containing blocking I/O — worse than either pure option, since FastAPI runs a plain `def` handler in a threadpool. Django: `SynchronousOnlyOperation` from ORM calls under a running loop, the `a`-prefixed queryset variants, and N+1 via missing `select_related`/`prefetch_related`. Plus request-scoped state parked in module globals, and missing timeouts on outbound calls. |261| **Data / scripts** | Reproducible seeds; float and NaN handling (`math.isclose` needs a positive `abs_tol` to compare against zero at all, and NaN is never close to anything including itself); chunked reads over `read()`. Where a hand-written table of examples guards a real invariant, recommend hypothesis. |262263## 6. Test quality264265Module-level state and import-time side effects are in `references/boundaries.md` §8 — they266belong to the same review pass as the other boundary items. What follows is tests.267268- **Asserting private state instead of rendered behaviour** — `app._inbox`, `app._active_tab`.269 A change that correctly updates the list but fails to render it still passes.270- **Fixed-iteration event-loop pumps as a worker wait** — `for _ in range(5): await pilot.pause()`,271 with the number varying across tests. Every such test is timing-dependent by construction;272 recommend the framework's real wait (`workers.wait_for_complete`).273- **Monkeypatching private internals, and the double-patch tell** — the same name patched in two274 modules because `from X import y` creates a second binding. A third importer silently gets the275 real function and the stub quietly stops covering it, with no failure.276- **Tests fabricating an untyped contract** — hand-built `Namespace(...)` objects standing in for277 a real parser; a downstream cost of §2's `args: Any`.278- **Negative assertions that pin nothing** — `assert "Metro" not in text` passes for every wrong279 renderer that happens not to print that word. Keep the ones naming a specific thing that would280 otherwise have happened (`assert not path.exists()` after a delete, `assert secret not in err`).281282## P. Project-level checks — `--all` only283284Repo-wide configuration. It changes rarely, so raising it on a diff review is noise.285286- **ruff `select` vs `extend-select`.** `select` *replaces* the 413-rule default set, so a project287 with a hand-written `select` is usually running fewer rules than an unconfigured `ruff check`.288 Diff the prefixes against the defaults and report what's lost — commonly all 10 `DTZ` (naive289 datetime), all 10 `ASYNC`, plus `TRY`, `LOG`, `G`, `TC`, `PIE`, `PERF`. Recommending290 `extend-select` fixes the whole category at once. Note that 18 opinionated `E`/`F` rules were291 *removed* from the 0.16 default set (`E401`, `E402`, `E701`–`E703`, `E711`–`E714`, `E721`,292 `E731`, `E741`–`E743`, `F403`, `F405`, `F406`, `F722`), so a repo selecting bare `E`/`F` must293 keep those listed explicitly to retain them.294- **mypy strictness.** Plain mypy does not check the bodies of unannotated functions at all. Where295 a codebase has many partially-annotated defs, stage it: `check_untyped_defs`, then296 `disallow_incomplete_defs`, then `strict`.297- **pytest configuration** — `--strict-markers`, `--strict-config`, `filterwarnings = ["error"]`,298 a coverage threshold, and whether `asyncio_mode` matches how the tests are actually marked.299- **Whether the repo has a good primitive that call sites bypass** — atomic write, lock, coercion300 helper. Finding the divergent copies is a whole-repo sweep; a diff review only checks whether301 *this* change bypassed it.302- **Encoding discipline across all readers**, which is only visible in aggregate.303304## Do NOT flag these305306- **Anything in §P, on a diff review.** Lint and type configuration are project properties; this307 diff did not change them.308309Already mechanical, or wrong. Check Step 0 before suppressing — if the project's config doesn't310reach the rule, fold it into the one-time recommendation instead of reporting each occurrence.311312- **Mutable default arguments** (`B006`), function calls in defaults (`B008`), mutable class313 defaults (`RUF012`) — and the dataclass decorator raises on them anyway.314- **Late-binding closures in loops** (`B023`), `lru_cache` on methods (`B019`).315- **Naive datetimes** — all ten `DTZ` rules are on by default. The best-covered category ruff has.316- **Blind `except` *detection*** (`BLE001`, `E722`) — the judgment of whether the handler does317 anything useful stays yours.318- **PEP 695 generic syntax** (`UP046`, `UP047`), import sorting (`I001`), modern-syntax rewrites319 (`UP`).320- **`print` in a CLI** — see §5.321- **Demanding Pydantic.** A stdlib dataclass plus a perimeter validator is a complete answer; a322 validation library is a dependency decision, not a review finding.323- **Demanding `ty`.** It is 0.0.x with no API stability commitment. `pyrefly` is production-ready324 if mypy's speed is a real problem — but mypy `--strict` is not a finding to begin with.325- **Docstring coverage** (`D`) unless the project already enforces it.326327328## Output Format329330```markdown331## Python Review: {scope}332333### Baseline334{Project shape, and whether `B904` is reachable (it decides whether exception chaining is yours to335review). **At `--all` only:** the §P results. On a diff review, omit this block unless something in336it changes what you reported.}337338### Critical Issues (Must Fix)339- {file}:{line} — {category}: {description}340 **Why it's not a ruff or mypy finding:** {what judgment this needed}341 **Impact:** {what breaks}342 **Fix:** {model change / boundary validation / real failure path — with code}343344### Improvements (Should Fix)345- {file}:{line} — {category}: {description}346 **Fix:** {solution}347348### Suggestions (Nice to Have)349- {file}:{line} — {category}: {description} — {suggested change}350351```352353If `--multi` was used, append one subsection per advisor that responded (titled with the advisor's354name as reported by `second-opinion`), then a **Cross-Model Agreement** subsection.355356## Examples357358**Validated data re-widened:**359> /review-python --staged360361A 400-line schema validator proves the exact shape of each resource spec, then stores the result362as `dict[str, Any]`. Downstream, `provision()` re-checks `isinstance(spec.get("range"), list)` and363raises on an unknown `type` — branches that cannot execute, and which permanently depress the364coverage number. Reports Nice to Have on those facts; Should Fix needs demonstrated meaningful365maintenance cost or a failing supported path. A `TypedDict` union keyed on a `Literal` `type` field turns the366final `else` into an `assert_never` type error and deletes five defensive raises. Not a mypy367finding: `Any` conforms to every consumer, so mypy has no discriminator to narrow on and cannot368see the branches as unreachable.369370**Blocking the event loop indirectly:**371> /review-python --changed372373An `async` worker pushes a progress modal, then calls `cmd_roundup(...)`, which three frames down374scans every session directory, calls `time.sleep`, runs `shutil.rmtree`, and issues N sequential375LLM subprocesses with no `timeout=`. Reports Should Fix — the modal cannot paint and keystrokes are dead376until it returns; fix with `asyncio.to_thread` or `thread=True`, and add a timeout. `ASYNC221` is377silent because the subprocess call is not lexically inside the `async def`.378379**Hierarchy bypassed:**380> /review-python381382`errors.py` defines `ApplicationError(exit_code, is_error)` with `UsageError` (exit 2) and383`MissingRecipeError` (exit 0). The code raises 61 raw `ValueError`s, four of them in a function384that raises `UsageError` correctly on the line above. Reports Should Fix — every one renders identically385through the generic handler and exits 1, discarding the distinctions the hierarchy exists to carry.386`TRY002` only catches `raise Exception`; `ValueError` is a perfectly ordinary raise.387388## Troubleshooting389390### Findings overlap with ruff or mypy391**Solution:** Check Step 0 — whether the project's config actually *reaches* that rule. Ruff's392defaults are large but `select` replaces them, so coverage is not inferable from the presence of a393config. If the rule runs, drop the finding. If it doesn't, fold it into the one-time baseline394recommendation rather than reporting each occurrence.395396### Can't tell whether a `dict` should be a dataclass397**Solution:** Ask where it was born. Handed to you by `json.loads`, a subprocess, or a wire format398and passed straight through → `TypedDict` describes it honestly. Constructed by your own code, or399carrying invariants across function boundaries → a dataclass, validated once at construction. The400deciding tell is whether any consumer has to ask "is this key present?" about a field the401producer always sets.402403### Can't tell whether a broad `except` is wrong404**Solution:** Read what the handler does, not what it catches. Re-raising as a domain error, or405logging with the traceback and continuing a loop that must not die, is fine. Returning `None` to a406caller that cannot distinguish "absent" from "failed" is not. And check the *callers* — a handler407can be correct while the caller's own `except` clause fails to match what actually propagates.408409## Notes410411- Model first, parse second, annotate third. Most `Any` and most defensive re-validation dissolve412 once the underlying data is modeled correctly.413- Respect project conventions in AGENTS.md / CLAUDE.md — a codebase may deliberately use plain414 dicts at a boundary, or standardize on returning `Result`-shaped tuples.415- Don't be dogmatic: `TypedDict` migrations, wrapper types, and exhaustive `match` all have costs.416 Recommend them where they prevent real bugs, not everywhere they are possible.417- **Test code:** patching *your own* module's private helper in a focused unit test is defensible;418 patching a name in two places because of import bindings, or asserting on private attributes419 instead of rendered output, is not. Also flag `sleep`-based synchronization and real clock,420 network, or home-directory access in unit tests.421- Sources: the ruff 0.16 release notes and rule documentation (astral.sh); the CPython422 `asyncio`, `dataclasses`, `enum`, `contextlib`, `subprocess` and `logging` docs; the typing spec423 and guides at typing.python.org (exhaustiveness, distributing, re-export); PEP 654 and PEP 698;424 Alexis King, "Parse, don't validate"; Hynek Schlawack on hashes and equality; mypy's command-line425 reference. ruff and the type checker own the mechanical rules referenced above.