kieran-python-reviewer_skill

Overview

This skill applies Kieran's exacting Python code-review standards to changes in a repository. It enforces strict type-hinting, Pythonic patterns, testability, and low-regression practices while giving concrete, actionable suggestions. Use it to ensure code meets a very high quality bar before merge.

How this skill works

The reviewer inspects diffs or new files and flags regressions, missing type hints, non-Pythonic idioms, unclear names, and poor import/module structure. It prioritizes breaking changes and deletions, evaluates testability, and recommends module extraction, refactors, or small pragmatic improvements. Responses include explicit examples and suggested code edits or small snippets to illustrate fixes.

When to use it

• After implementing new Python features or endpoints
• When refactoring or modifying existing modules
• Before merging pull requests that change core logic or delete code
• When adding or changing public APIs or service classes
• When writing tests or adding complex business rules

Best practices

• Always add precise type hints for parameters and return values using modern 3.10+ syntax (e.g., list[str], A | None).
• Prefer extracting complexity into new modules/classes rather than increasing complexity in existing files.
• Make code easily testable: ask "How would I test this?" and extract hard-to-test pieces.
• Follow clear, descriptive naming so intent is obvious within five seconds.
• Organize imports by stdlib, third-party, local; use absolute imports and avoid wildcard or circular imports.
• Use Pythonic patterns: context managers, f-strings, dataclasses/Pydantic, and pathlib for file I/O.

Example use cases

• Review a new FastAPI endpoint for type hints, input validation, and separation of concerns.
• Audit a refactor of an EmailService to ensure attachments handling is testable and well-named.
• Check deletions to verify no regressions and that removed logic is intentionally moved or covered by tests.
• Evaluate a new business-rule module and recommend extraction or simplification if it mixes concerns.
• Give actionable fixes for non-Pythonic code (e.g., replace manual resource handling with context managers).