# 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