type-checking_skill

Overview

This skill helps developers add and repair Python type hints using Pyright or BasedPyright for gradual type checking. It emphasizes non-invasive fixes, prioritizes concrete typing over ignores, and checks that type changes do not alter runtime behavior. Use it to expand type coverage, resolve type checker errors, and improve long-term code quality.

How this skill works

Run the type checker against a file or directory, inspect reported errors, and apply fixes following a prioritized sequence: add precise annotations, correct decorator and return types, use cast() when static typing cannot capture runtime shapes, and only then add type: ignore for exceptional cases. After fixes, run tests and review diffs to ensure no behavioral changes.

When to use it

• When Pyright/BasedPyright or mypy reports type errors you want to resolve
• When introducing or expanding type hints across a module or package
• When a function or decorator has incorrect or missing return types
• When reducing uses of Any, weak container types, or raw dict/list annotations
• When merging changes that require type-safety verification before commit

Best practices

• Minimize logic changes: type fixes should not change runtime behavior
• Run tests and git diff main after typing changes to detect regressions
• Prefer specific types over Any or unparameterized containers
• Use typing.cast() for runtime-compatible-but-statically-opaque values
• Avoid # type: ignore unless the issue is a runtime dynamic attribute or external library quirk
• Fix root causes first (Optional, return types, imports) before ignoring errors

Example use cases

• Fixing a Pyright error where a parameter is annotated as str but None is passed — change to Optional[str]
• Annotating Pydantic Field defaults correctly to satisfy the type checker without changing behavior
• Replacing list[Any] or dict with concrete generic types like list[DataItem] or dict[str, Result]
• Using cast() to tell the type checker a runtime-validated list matches a protocol before calling typed functions
• Applying type: ignore[attr-defined] for a dynamically attached function attribute from a third-party runtime hook