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

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

# 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+)

# 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)

# Before
from typing import TypeAlias
Vector: TypeAlias = list[float]

# After
type Vector = list[float]

Broad Exception Handling

# 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