ARTIFACTS TO LOAD:
- [ ] Modernization plan (Phase 3 output)
- [ ] Plan review feedback (Phase 4-5 output)
- [ ] Interface definitions (Phase 7 output)
- [ ] Failing test files (Phase 8 output)

uv run pytest <file_paths/> -v --tb=short 2>&1 | head -100

IMPLEMENTATION ORDER:
1. Type definitions (TypeAlias, TypedDict, Protocol)
2. Data structures (dataclass, Pydantic models)
3. Utility functions (pure functions, no side effects)
4. Core business logic
5. Integration points (API clients, file I/O)
6. Entry points (CLI commands, handlers)

FOR EACH IMPLEMENTATION ITEM:
1. Read the interface/protocol definition
2. Read the failing test(s) for this component
3. Implement the function/class
4. Run targeted tests: uv run pytest -k "test_name" -v
5. If fails: debug and fix
6. If passes: move to next item

# Use modern union syntax
def process(data: str | None) -> dict[str, Any]:
    ...

# Use TypeGuard for narrowing
def is_valid_user(obj: object) -> TypeGuard[User]:
    return isinstance(obj, dict) and "id" in obj

from typing import Protocol

class Serializable(Protocol):
    def to_dict(self) -> dict[str, Any]: ...

def save(item: Serializable) -> None:
    data = item.to_dict()
    ...

from dataclasses import dataclass, field

@dataclass(slots=True, frozen=True)
class Config:
    name: str
    options: list[str] = field(default_factory=list)

from pydantic import BaseModel, Field

class APIResponse(BaseModel):
    status: int = Field(ge=100, le=599)
    data: dict[str, Any]

    model_config = {"strict": True}

# httpx for async HTTP
async with httpx.AsyncClient() as client:
    response = await client.get(url)

# orjson for fast JSON
data = orjson.loads(response.content)
output = orjson.dumps(result, option=orjson.OPT_INDENT_2)

# tomlkit for TOML with comments preserved
doc = tomlkit.parse(content)
doc["section"]["key"] = value

# Run full test suite
uv run pytest <file_paths/> -v --tb=short

# If failures remain, focus on failing tests
uv run pytest <file_paths/> -v --tb=long -x  # Stop on first failure

# Format check
uv run ruff format --check <file_paths/>

# Lint check
uv run ruff check <file_paths/>

# Type check — match hooks/CI; ty when repo runs ty (do not infer mypy from [tool.mypy] alone)
uv run ty check <file_paths/>
# uv run mypy <file_paths/> --strict

uv run pytest <file_paths/> -v --cov --cov-report=term-missing