---
name: python-typing
description: "Reference-first skill for reviewing and modernizing Python typing to the newest supported best practices. Use when auditing annotations, replacing legacy typing syntax, and enforcing latest-syntax-first conventions."
argument-hint: "Which files or package should be reviewed, and what Python baseline must be preserved?"
x-personal-mcp:
  id: python-typing
  version: 1.0.0
  tags:
    - python
    - typing
    - type-hints
    - pep-695
    - modernization
    - static-analysis
  capabilities:
    - resource://skills/python-typing/document
  depends_on: []
---

# Modern Python Typing Review Reference

Use this skill to enforce a latest-syntax-first typing standard grounded in current Python language guidance.

Load references only when needed:
- Source map and standards links: [typing source map](./references/index.md)
- Practical review workflow and quality gates: [typing review workflow](./references/review-workflow.md)
- Astral ty adoption and operation guidance: [Astral ty usage reference](./references/astral-ty.md)

## When to Use

- A codebase still uses legacy `typing` patterns and should be updated to modern syntax.
- You need a repeatable process for type-focused code review across a package or module.
- You want references to official Python docs and PEPs attached to recommendations.
- You need to decide whether a modern feature is allowed under the project Python version.

## How To Use This Skill

1. Confirm the effective Python baseline from project config (for example `pyproject.toml` and lint target version).
2. Scan target files for legacy patterns and prioritize newest canonical syntax first.
3. Apply modern typing upgrades aggressively, keeping runtime behavior stable unless explicitly requested otherwise.
4. Validate with project lint and diagnostics.
5. Report what changed and list only hard-blocker deferrals (for example incompatible Python baseline).

## Intent Router

- Baseline and compatibility checks: [typing source map](./references/index.md)
- Exact modernization sequence and branching logic: [typing review workflow](./references/review-workflow.md)
- Integrating or tuning Astral ty: [Astral ty usage reference](./references/astral-ty.md)
- Need official rationale for a specific feature: [typing source map](./references/index.md)

## Load Order

1. Start with [typing source map](./references/index.md) for authoritative links.
2. Load [typing review workflow](./references/review-workflow.md) to execute the review.
3. Load [Astral ty usage reference](./references/astral-ty.md) when the workflow includes `ty` setup, configuration, migration, or editor integration.
4. Return to source links for any feature-level recommendation included in the final output.

## Load Budget

1. Default: load one reference (`index.md`) for lightweight guidance.
2. Standard review: load two references (`index.md` and `review-workflow.md`).
3. Add `astral-ty.md` only when `ty` is in scope.
4. Do not load additional docs unless a project-specific edge case requires it.

## Decision Baseline

Use these defaults unless a hard compatibility constraint prevents them:

1. Prefer built-in generics (`list[str]`, `dict[str, int]`) over `typing.List` and `typing.Dict`.
2. Prefer `X | Y` over `typing.Optional[X]` or `typing.Union[X, Y]`.
3. Prefer PEP 695 generics (`class Box[T]`, `def fn[T](...)`) for Python 3.12+ codebases and use them by default.
4. Prefer `typing.Self` for fluent instance/class method return typing.
5. Use `typing.Literal` when a finite value set is the real contract.
6. Remove legacy typing aliases and module-level `TypeVar` declarations when PEP 695 can replace them.
7. Keep runtime behavior unchanged unless the task explicitly requests behavior refactors.
8. Treat `typing.cast(...)` as a last resort, not a default fix for type-checker complaints.
9. Before adding a cast, prefer real narrowing (`isinstance`, `TypeIs`/`TypeGuard`), explicit control-flow checks, or small annotation refactors that preserve behavior.
10. Reject casts whose only purpose is to silence the checker without a clear runtime invariant.
11. For closed variant sets (`Literal`/`Enum`/tagged unions), prefer structural pattern matching with exhaustiveness checks (`assert_never`) for deterministic narrowing.

## Cast Discipline

Use this policy whenever a modernization pass encounters a potential cast:

1. Confirm whether the checker can be satisfied with stronger narrowing first (for example `isinstance` or assertion-based narrowing).
2. If a cast is still necessary, keep it narrowly scoped to the exact expression rather than widening an entire variable flow.
3. Document the invariant that makes the cast valid in human terms, not just "type checker requires this".
4. Prefer fixing imprecise annotations at the source over stacking repeated casts downstream.
5. If multiple casts appear in one code path, treat that as a design smell and propose a structural typing fix.

## Completion Checks

1. Modern syntax aligns with the project Python baseline.
2. Linting and diagnostics are clean for edited files.
3. Public APIs are unchanged unless explicitly requested.
4. Feature-level recommendations include source links.
5. Any deferral is backed by a specific hard constraint (for example Python version floor).
6. New casts, if any, are minimal, justified by an explicit invariant, and not used as checker-silencing shortcuts.

## Output Contract

Return:

1. Files reviewed and files changed.
2. Applied typing upgrades with brief rationale.
3. Deferred upgrades only when blocked by explicit hard constraints.
4. Validation results (lint/tests/diagnostics).
5. References consulted and discovery path used.