python typing skill

docs/skills/python-typing/references/index.md

@@ -0,0 +1,28 @@
+# Python Typing Source Map
+
+Use this page as the canonical source index when making typing modernization recommendations.
+
+## Core Language and Library Docs
+
+- [Typing module documentation](https://docs.python.org/3/library/typing.html)
+- [Typing specification (typing.python.org)](https://typing.python.org/)
+- [Built-in types and generic aliases](https://docs.python.org/3/library/stdtypes.html)
+
+## Modernization PEPs
+
+- [PEP 585: Type Hinting Generics In Standard Collections](https://peps.python.org/pep-0585/)
+- [PEP 604: Allow writing union types as `X | Y`](https://peps.python.org/pep-0604/)
+- [PEP 673: Self Type](https://peps.python.org/pep-0673/)
+- [PEP 695: Type Parameter Syntax](https://peps.python.org/pep-0695/)
+
+## Advanced Typing PEPs (Load on Demand)
+
+- [PEP 612: Parameter Specification Variables](https://peps.python.org/pep-0612/)
+- [PEP 646: Variadic Generics](https://peps.python.org/pep-0646/)
+- [PEP 647: User-Defined Type Guards](https://peps.python.org/pep-0647/)
+- [PEP 655: Required and NotRequired for TypedDict](https://peps.python.org/pep-0655/)
+- [PEP 742: Narrowing types with TypeIs](https://peps.python.org/pep-0742/)
+
+## Version Gate Reminder
+
+Before recommending syntax upgrades, verify the project's supported Python range and lint target so recommendations match runtime constraints.

docs/skills/python-typing/references/review-workflow.md

@@ -0,0 +1,45 @@
+# Typing Review Workflow
+
+This workflow is distilled from practical typing modernization passes and is designed for latest-syntax-first upgrades.
+
+## Step-by-Step Process
+
+1. Identify the Python baseline from project config (`requires-python`, lint target version, toolchain constraints).
+2. Scan target files for legacy typing patterns and repeated opportunities.
+3. Apply highest-value modern syntax updates first:
+   - `typing.List`/`typing.Dict` -> built-in generics.
+   - `Optional[T]`/`Union[A, B]` -> `T | None` / `A | B`.
+4. Upgrade generic declarations to PEP 695 syntax where baseline allows:
+   - `TypeVar` module globals -> local type parameters in classes/functions.
+5. Tighten domain contracts where clear:
+   - replace unconstrained `str` with `Literal[...]` for finite known values.
+   - use `Self` for fluent APIs.
+6. Keep edits minimal and avoid behavior changes unless requested.
+7. Validate with lint and editor diagnostics.
+8. Report applied changes, hard-blocker deferrals, and sources consulted.
+
+## Decision Points and Branching
+
+- If Python baseline is below 3.12:
+  - use the newest syntax available under that baseline, and document exactly what blocked PEP 695.
+- If a legacy annotation is public API and downstream tooling compatibility is unknown:
+  - still modernize syntax unless there is a confirmed breakage risk with a named downstream constraint.
+- If replacing `TypeVar` with PEP 695 affects readability debates only:
+  - still prefer PEP 695; readability preference alone is not a blocker.
+- If a stricter type (for example `Literal`) may reject existing runtime inputs:
+  - apply only when the input contract is already finite; otherwise defer with a contract-change note.
+
+## Quality Criteria
+
+1. All edits are syntax-valid for the target Python versions.
+2. Lint and diagnostics pass for edited files.
+3. Runtime behavior is unchanged for modernization-only tasks.
+4. Recommendations cite authoritative sources.
+5. Output clearly separates "changed now" from hard-blocked follow-up items.
+
+## Suggested Validation Commands
+
+- `uv run ruff check <paths>`
+- `uv run pytest -q` (or targeted tests where available)
+
+Use repository-preferred test invocation conventions when they differ.