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

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.