Python Type Hint Reviewer

Overview

This skill validates the application of type hints and code quality in newly written code by the Agent. The Agent must review the code diffs to achieve the following goals:

1. Ensure type hinting is present as the primary safety device for stable Python code execution.
2. Guarantee a clear data structure, which reduces the causes of hallucination and prevents the Agent from inferring incorrect logic.

Trigger Condition

This skill must be triggered specifically when uncommitted changes (diffs) are generated by the Agent or new files are created. This focused approach is taken instead of reviewing the entire legacy codebase to reduce scope and ensure the immediate quality of new code.

Specific moments for review include:

• The stage between code generation by the Agent and the Git commit (e.g., during a pre-commit check phase).
• The final review step before the Agent presents the modified code to the user.

What role should the agent play

The Agent must play the role of a strict auditor for type hint compliance. If any modifications are required, the Agent must explicitly proceed with user confirmation before applying the changes.

1. Comprehensive Type Hint Coverage

   • Ensure comprehensive type annotations are applied to all functions and methods.
   • To prevent Silent Failure where the type checker (like MyPy) skips checking internal logic, test functions—even those without parameters—must explicitly specify -> None in their signature.

2. Specific Type Hinting Principles

   • Container Typing using Abstract Types
     • Container types like list, tuple, or dict should be typed using abstract types from collections.abc.
     • Use Sequence or Mapping for read-only objects, and only use MutableSequence or MutableMapping for modifiable objects.
     • This clearly communicates the intent and fundamentally prevents the Agent from writing code that mistakenly manipulates original data.
   • Typing ‘Returns Nothing’ (-> None): Functions that only perform side-effects and return no value must be explicitly typed with -> None. ◦ This context prevents the Agent from hallucinating code that unnecessarily assigns the function's return value to a variable (e.g., result = func()).
   • Class Typing: ◦ Explicitly declare and type instance variables (attributes) within the class body. ◦ Use ClassVar to clearly distinguish between class variables and instance variables. ◦ Apply consistent return type typing to all methods, including init, which must be typed as -> None.

3. Data Structuring (Dataclass Recommendation)

   • The Agent should recommend using dataclass instead of standard dicts.
   • Using dict blackboxes the data structure, making it difficult to understand required keys and value types, which can be a source of Agent hallucination.
   • dataclass supports Dot Notation (obj.attr), allowing for immediate typo detection by IDEs/Linters and enabling the Agent to quickly and accurately grasp the data structure's attributes.
   • If immutability is required, verify the use of the frozen=True setting.

4. Package and Module Organization

   • Circular dependencies should be avoided, and the Agent should be encouraged to refactor the code to avoid them.
   • High level packages should be dependent on low level packages

5. Review for Potential Pitfalls

   • Prevent Unintended Any Review for cases where generic type parameters are missing (e.g., declaring list without specifying its contents), which defaults to list[Any]. The Agent must ensure specific internal types are provided (e.g., list[int]).
   • Untyped Decorators Check if the Agent used decorators that lack proper typing, as this can cause the decorated function's signature to degrade to Any (e.g., (*args, **kwargs) -> Any), eliminating type inference for the internal logic.
   • Check for Type Hint Lies The Agent must diligently review its own code for situations where the type hint (the "hint") contradicts the actual runtime behavior. This includes detecting the misuse or overuse of typing.cast to artificially silence linter errors. Since type hints are not enforced at runtime, the Agent must ensure the hints accurately reflect the code's logic.