fix

.github/skills/python-review/references/fix-rules.md

@@ -0,0 +1,97 @@
+# Fix Application Rules
+
+Rules the agent must follow when applying accepted review fixes.
+
+## General Rules
+
+1. **One file at a time** — edit files sequentially, not in parallel, to avoid conflicts
+2. **Minimal diff** — change only what is needed; do not reformat unrelated code
+3. **Preserve comments** — keep existing comments unless they are part of the fix
+4. **No behaviour changes** — fixes must not alter runtime behaviour unless the original was a bug
+5. **Add imports sparingly** — only add imports that are strictly required by the fix
+
+## Type Annotation Fixes
+
+- Add annotations using Python 3.13+ syntax: `X | None` not `Optional[X]`
+- Use `list[str]` not `List[str]`, `dict[str, int]` not `Dict[str, int]`
+- For functions with no return: annotate as `-> None`
+- For `*args` / `**kwargs`: annotate properly, e.g. `*args: str`, `**kwargs: int`
+- Do not add `from __future__ import annotations` — use native syntax directly
+
+## mypy `# type: ignore` Usage
+
+- Never add bare `# type: ignore` — always use specific code: `# type: ignore[assignment]`
+- Only use `type: ignore` as last resort when fixing the root cause is not feasible
+- Add a comment explaining why: `# type: ignore[misc]  # third-party stub incomplete`
+
+## ruff Auto-fix Rules
+
+- Run `ruff check --fix <file>` only for safe auto-fixable rules (F401, UP*, I*)
+- Do NOT use `--unsafe-fixes` without explicit user confirmation
+- After auto-fix, re-read the file to verify no logic was altered
+
+## Mutable Default Arguments
+
+```python
+# Before
+def process(items: list[str] = []) -> None: ...
+
+# After
+def process(items: list[str] | None = None) -> None:
+    if items is None:
+        items = []
+```
+
+## Union Type Modernization (Python 3.13+)
+
+```python
+# Before
+from typing import Optional, Union
+def f(x: Optional[str]) -> Union[int, str]: ...
+
+# After
+def f(x: str | None) -> int | str: ...
+```
+
+Remove now-unused `Optional` / `Union` imports after rewriting.
+
+## TypeAlias Modernization (PEP 695)
+
+```python
+# Before
+from typing import TypeAlias
+Vector: TypeAlias = list[float]
+
+# After
+type Vector = list[float]
+```
+
+## Broad Exception Handling
+
+```python
+# Before
+try:
+    ...
+except Exception:
+    pass
+
+# After — option A: log and re-raise
+except Exception:
+    logger.exception("Unexpected error")
+    raise
+
+# After — option B: specific exception (preferred when possible)
+except ValueError as exc:
+    logger.warning("Invalid value: %s", exc)
+```
+
+## Post-Fix Validation Sequence
+
+After applying all accepted fixes to a file:
+
+1. `mypy --strict <file>` — must return exit code 0
+2. `ruff check <file>` — must return exit code 0
+3. If any new violations appear that were NOT in the original report — fix them silently and note in the summary
+4. Report final status:
+   - ✅ Clean — zero violations remaining
+   - ⚠️ Remaining — list unresolved items with reason