better typing

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

@@ -7,6 +7,13 @@ Use this page as the canonical source index when making typing modernization rec
 - [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)
+- [Python language reference: `match` statement](https://docs.python.org/3/reference/compound_stmts.html#the-match-statement)
+- [PEP 634: Structural Pattern Matching specification](https://peps.python.org/pep-0634/)
+- [typing.cast reference (runtime no-op)](https://docs.python.org/3/library/typing.html#typing.cast)
+- [Typing spec directives for `cast()`](https://typing.python.org/en/latest/spec/directives.html#cast)
+- [Mypy type narrowing and casts guidance](https://mypy.readthedocs.io/en/stable/type_narrowing.html#casts)
+- [Typing guide: exhaustiveness and `assert_never`](https://typing.python.org/en/latest/guides/unreachable.html#assert-never-and-exhaustiveness-checking)
+- [Mypy: `Literal`/`Enum` exhaustiveness with `match`](https://mypy.readthedocs.io/en/stable/literal_types.html#exhaustiveness-checking)
 
 ## Tooling References
 

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

@@ -29,6 +29,46 @@ This workflow is distilled from practical typing modernization passes and is des
 - 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.
 
+## Deterministic Narrowing with `match`
+
+Use structural pattern matching when the domain is a closed set (for example tagged unions, enum dispatch, or finite literal variants).
+
+1. Prefer `match` over long `if`/`elif` ladders when each branch represents a distinct variant.
+2. For tagged unions, match the discriminant and extract payload fields in the same case.
+3. Add a default `case _:` branch with `assert_never(...)` to enforce exhaustiveness in static analysis.
+4. Keep patterns explicit and side-effect-light; avoid relying on bindings from failed matches.
+
+Example with a tagged `TypedDict` union:
+
+```python
+from typing import Literal, TypedDict, assert_never
+
+
+class NewJobEvent(TypedDict):
+  tag: Literal["new-job"]
+  job_name: str
+
+
+class CancelJobEvent(TypedDict):
+  tag: Literal["cancel-job"]
+  job_id: int
+
+
+type Event = NewJobEvent | CancelJobEvent
+
+
+def route(event: Event) -> str:
+  match event:
+    case {"tag": "new-job", "job_name": job_name}:
+      return f"enqueue:{job_name}"
+    case {"tag": "cancel-job", "job_id": job_id}:
+      return f"cancel:{job_id}"
+    case _:
+      assert_never(event)
+```
+
+This pattern makes narrowing deterministic per branch and surfaces missing variants as type-checker errors during review.
+
 ## Quality Criteria
 
 1. All edits are syntax-valid for the target Python versions.