jiro-python-checklist

name	jiro-python-checklist
description	Comprehensive Python code review checklist for Jiro. Obsessive, methodical verification of every Python-specific concern. Use as part of Jiro's multi-pass review methodology.
context	inherit
agent	general-purpose
model	sonnet
allowed-tools	["Read","Grep","Glob"]

Jiro Python Checklist - Obsessive Verification Protocol

Purpose

This checklist ensures NO Python-specific issue escapes review. Execute every section. Check every item. Document every finding. Leave nothing to assumption.

Execution Protocol

For each file under review:

1. Execute every checklist section
2. Mark each item: PASS, FAIL, or N/A
3. Document exact line numbers for every FAIL
4. Do not skip sections - if N/A, explicitly state why

---

SECTION 1: IMPORTS

1.1 Import Organization

• Standard library imports first (os, sys, typing, etc.)
• Third-party imports second (pydantic, pytest, etc.)
• Local/project imports last
• Blank line between each import group
• Alphabetical within each group (if project convention)

1.2 Import Hygiene

• NO UNUSED IMPORTS - Every import must be used
• No wildcard imports (from x import *) unless explicitly justified
• No circular import potential (check for late imports in functions)
• TYPE_CHECKING block used for type-only imports that would cause cycles
• No deprecated module imports (check against Python version)

1.3 Import Style

• Prefer from x import y over import x when using only y
• Prefer import x when using multiple x.a, x.b, etc.
• No single-item imports spread across multiple lines unnecessarily
• No duplicate imports

Verification command: grep -n "^import\|^from" <file>

---

SECTION 2: TYPE HINTS

2.1 Modern Type Syntax (Python 3.10+)

• Use list not List from typing
• Use dict not Dict from typing
• Use tuple not Tuple from typing
• Use set not Set from typing
• Use X | None not Optional[X]
• Use X | Y not Union[X, Y]
• No unnecessary imports from typing for built-in generics

2.2 Type Hint Coverage

• All function parameters have type hints
• All function return types declared (including -> None)
• All class attributes have type annotations
• Instance variables annotated in __init__ or as class vars
• Module-level variables have type annotations if not obvious

2.3 Type Hint Correctness

• Generic types properly parameterized (list[str] not just list)
• Callable signatures correct (Callable[[int, str], bool])
• Self used for methods returning class instance
• TypeVar used appropriately for generics
• @overload used for methods with complex signatures
• No Any without explicit justification

Verification command: mypy --strict <file> 2>&1 | head -50

---

SECTION 3: NAMING CONVENTIONS

3.1 Case Conventions

• Classes: PascalCase (MyClass)
• Functions: snake_case (my_function)
• Variables: snake_case (my_variable)
• Constants: UPPER_SNAKE_CASE (MY_CONSTANT)
• Private: single underscore prefix (_private)
• Name-mangled: double underscore prefix (__mangled)
• Type variables: PascalCase (T, KeyType)

3.2 Naming Quality

• Names are descriptive and unambiguous
• No single-letter names except: i, j, k for indices; x, y for coordinates; e for exceptions; f for file handles; _ for discarded values
• No abbreviations unless universally understood
• Boolean variables/functions use is_, has_, can_, should_ prefix
• Collection names are plural
• No shadowing built-in names (id, type, list, etc.)
• No name reuse in nested scopes

3.3 Consistency

• Similar concepts use similar naming patterns
• Pairs are symmetric (get/set, start/stop, open/close)
• Names match domain terminology if applicable

---

SECTION 4: FUNCTION DESIGN

4.1 Function Signatures

• Parameters ordered: required, optional, *args, keyword-only, **kwargs
• Keyword-only arguments after * for clarity
• Default values are immutable (NOT def f(items=[]))
• No more than 5-7 parameters (use dataclass/config if more)
• *args and **kwargs used sparingly and documented

4.2 Function Bodies

• Functions do one thing
• Functions are under 30 lines (prefer under 20)
• Single return type (no returning both list and None without Optional)
• Early returns for guard clauses
• No nested functions unless closure needed
• No side effects in functions that appear pure

4.3 Documentation

• All public functions have docstrings
• Docstring format consistent (Google, NumPy, or Sphinx)
• Args section documents every parameter
• Returns section documents return value
• Raises section documents exceptions that may be raised
• Examples included for complex functions

---

SECTION 5: CLASS DESIGN

5.1 Class Structure

• Class docstring present
• __init__ is first method
• Class/static methods grouped together
• Public methods before private methods
• Properties grouped logically
• __slots__ used if many instances created

5.2 Inheritance

• Inheritance hierarchy is shallow (max 3 levels)
• Abstract methods in ABC are implemented
• super() called correctly in overrides
• Liskov substitution principle respected
• Composition preferred over inheritance where appropriate

5.3 Data Classes

• Use @dataclass for data containers
• Use frozen=True for immutable data
• Use slots=True for memory efficiency
• Field defaults use field(default_factory=...) for mutables

5.4 Special Methods

• __repr__ implemented for debugging
• __eq__ implemented if equality comparison needed
• __hash__ consistent with __eq__
• Context managers implement __enter__ and __exit__
• Iterables implement __iter__ (and __len__ if known)

---

SECTION 6: ERROR HANDLING

6.1 Exception Types

• Specific exceptions raised (not bare Exception)
• Specific exceptions caught (not bare except:)
• Custom exceptions inherit from appropriate base
• Exception messages are actionable

6.2 Exception Handling

• try blocks minimal (only code that can raise)
• except blocks handle or re-raise (no silent swallowing)
• finally used for cleanup (or context managers)
• else block used for code that should run only if no exception

6.3 Error Prevention

• Assertions used for programmer errors, not runtime checks
• Input validation at public API boundaries
• Fail fast - errors caught close to their source
• No except Exception as e: pass

---

SECTION 7: CODE QUALITY

7.1 Complexity

• No function exceeds cyclomatic complexity of 10
• No deeply nested code (max 4 levels)
• Complex conditionals extracted to well-named functions
• Long boolean expressions broken into named variables

7.2 DRY (Don't Repeat Yourself)

• No copy-pasted code blocks
• Common patterns extracted to utilities
• Magic numbers/strings extracted to constants
• But: no premature abstraction (rule of 3)

7.3 Code Smells

• No god classes (classes doing too much)
• No feature envy (methods accessing other object's data extensively)
• No data clumps (same groups of data appearing together)
• No primitive obsession (use domain types)
• No long parameter lists
• No dead code (unreachable, commented out)

7.4 Python-Specific

• Use list/dict/set comprehensions where clearer
• Use generators for large sequences
• Use enumerate not manual index tracking
• Use zip for parallel iteration
• Use with for resource management
• Use pathlib.Path not os.path
• Use f-strings not .format() or %

---

SECTION 8: SECURITY

8.1 Input Handling

• No eval() or exec() on user input
• No pickle on untrusted data
• SQL queries parameterized (no string formatting)
• File paths validated (no path traversal)
• No shell=True with user input

8.2 Secrets

• No hardcoded secrets, passwords, API keys
• No secrets in logs
• Environment variables for configuration
• Secrets excluded from version control

8.3 Dependencies

• Dependencies pinned to specific versions
• No known vulnerable versions
• Minimal dependency footprint

---

SECTION 9: PERFORMANCE

9.1 Algorithmic

• Appropriate data structures used
• No O(n²) where O(n) or O(n log n) possible
• No repeated expensive operations in loops
• Caching/memoization for expensive repeated calls

9.2 Python-Specific Performance

• No string concatenation in loops (use list + join)
• No repeated attribute lookups in hot paths
• __slots__ for memory-intensive classes
• collections.deque for queue operations
• set for membership testing
• bisect for sorted list operations

9.3 I/O

• Files read in chunks for large files
• Async I/O for concurrent operations where appropriate
• Connection pooling for database/HTTP
• Streaming for large responses

---

SECTION 10: TESTING

10.1 Test Coverage

• All public functions have tests
• Edge cases covered
• Error paths tested
• Happy path tested

10.2 Test Quality

• Tests are independent (no order dependency)
• Tests are deterministic (no flakiness)
• Test names describe what is tested
• Arrange-Act-Assert pattern followed
• Fixtures used for common setup
• Mocks used sparingly and appropriately

10.3 Test Organization

• Tests mirror source structure
• Unit tests separate from integration tests
• Fixtures in conftest.py
• Test data in separate files if large

---

OUTPUT FORMAT

For each file reviewed, produce:

### File: `path/to/file.py`

#### Section 1: Imports
- [PASS] 1.1 Import Organization
- [FAIL] 1.2 Import Hygiene
  - Line 23: Unused import `Iterable`
  - Line 30: Unused import `tensorlogic`
- [PASS] 1.3 Import Style

#### Section 2: Type Hints
...

FINAL VERIFICATION

After completing all sections:

1. Re-read findings
2. Verify each finding has exact line number
3. Verify each finding has clear description
4. Verify no section was skipped
5. Count total: X PASS, Y FAIL, Z N/A