prompts/docs/skills/python-typing/SKILL.md

name, description, x-personal-mcp

name	description	x-personal-mcp
python-typing	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.	id version tags capabilities python-typing 1.0.0 python typing type-hints pep-695 modernization static-analysis resource://skills/python-typing/document

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
• Practical review workflow and quality gates: typing review workflow
• Astral ty adoption and operation guidance: Astral ty usage reference

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
• Exact modernization sequence and branching logic: typing review workflow
• Integrating or tuning Astral ty: Astral ty usage reference
• Need official rationale for a specific feature: typing source map

Load Order

1. Start with typing source map for authoritative links.
2. Load typing review workflow to execute the review.
3. Load Astral ty usage reference 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.