┌─────────────────────────────────────────────────────────────────────────────┐
│                         STINKYSNAKE WORKFLOW                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Phase 1: STATIC ANALYSIS                                                   │
│  ├── Run formatters (ruff format)                                           │
│  ├── Run linters (ruff check --fix)                                         │
│  ├── Run type checkers (mypy, pyright)                                      │
│  └── Auto-fix all resolvable issues                                         │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 2: TYPE ANALYSIS                                                     │
│  ├── Determine minimum Python version                                       │
│  ├── Inventory all `Any` types                                              │
│  ├── Map type dependencies                                                  │
│  └── Identify typing gaps                                                   │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 3: MODERNIZATION PLANNING                                            │
│  ├── Plan Protocol usage for duck typing                                    │
│  ├── Plan Generic type parameters                                           │
│  ├── Plan TypeGuard narrowing                                               │
│  ├── Plan TypeAlias definitions                                             │
│  ├── Plan TypedDict for dict shapes                                         │
│  ├── Plan dataclass/Pydantic models                                         │
│  └── Plan library modernization (httpx, orjson, etc.)                       │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 4: PLAN REVIEW (context: fork)                                       │
│  ├── Review against pythonic best practices                                 │
│  ├── Verify against online references                                       │
│  ├── Check feasibility                                                      │
│  ├── Identify breaking changes                                              │
│  └── Produce review report                                                  │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 5: PLAN REFINEMENT                                                   │
│  └── Update plan based on review feedback                                   │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 6: DOCUMENTATION DISCOVERY                                           │
│  ├── Find docs requiring updates                                            │
│  └── Note what changes are needed                                           │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 7: INTERFACE DESIGN                                                  │
│  └── Create interfaces/protocols first                                      │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 8: TEST-FIRST (context: fork, python-pytest-architect)               │
│  ├── Write failing tests against interfaces                                 │
│  └── Stop after tests written                                               │
│           │                                                                 │
│           ▼                                                                 │
│  Phase 9: IMPLEMENTATION (/snakepolish)                                     │
│  ├── context: fork with python-cli-architect                                │
│  ├── Follow plans and implement functions                                   │
│  └── Run tests until passing                                                │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

# Format all Python files
uv run ruff format $ARGUMENTS

# Verify formatting
uv run ruff format --check $ARGUMENTS

# Fix all auto-fixable issues
uv run ruff check --fix $ARGUMENTS

# Fix unsafe fixes if appropriate
uv run ruff check --fix --unsafe-fixes $ARGUMENTS

# Run mypy
uv run mypy $ARGUMENTS

# Run pyright if configured
uv run pyright $ARGUMENTS

## Static Analysis Results

### Auto-Fixed
- [X] Formatting issues: N fixed
- [X] Import sorting: N fixed
- [X] Safe linting fixes: N fixed

### Requires Manual Resolution
| File:Line | Rule | Issue | Complexity |
|-----------|------|-------|------------|
| src/api.py:45 | ANN001 | Missing type annotation | Low |
| src/models.py:120 | B006 | Mutable default | Medium |

# Check pyproject.toml
grep -E "requires-python|python_requires" pyproject.toml

# Check setup.py if exists
grep -E "python_requires" setup.py

## Python Version Constraint

Minimum Version: Python 3.11
Reason: [from pyproject.toml requires-python = ">=3.11"]

Available Language Features:
- Native generics (list[str], dict[str, int])
- Union syntax (str | None)
- Pattern matching (match/case)
- Exception groups
- Self type
- TypeVarTuple
- Required/NotRequired in TypedDict

# Find explicit Any imports and usage
uv run rg "from typing import.*Any|: Any|-> Any" $ARGUMENTS

# Run mypy with strict mode to find implicit Any
uv run mypy --strict $ARGUMENTS 2>&1 | grep -E "has type.*Any|Implicit.*Any"

## Any Type Inventory

### Explicit Any Usage
| Location | Variable | Current Type | Proposed Type |
|----------|----------|--------------|---------------|
| api.py:23 | response | Any | dict[str, JSONValue] |
| utils.py:45 | callback | Any | Callable[[str], None] |

### Implicit Any (from untyped libraries)
| Location | Source | Mitigation |
|----------|--------|------------|
| client.py:12 | third_party.get() | Add type stub or cast |

## Type Dependency Map

Entry Points (public API):
- cli.main() -> int
- api.fetch_data(url: str) -> ???  # Needs typing

Internal Flow:
fetch_data() -> parse_response() -> validate() -> Model

Type Gaps:
- parse_response returns Any
- validate accepts Any

Skill(command: "modernpython")

# Before: Any for duck-typed objects
def process(handler: Any) -> None:
    handler.handle(data)

# After: Protocol defines required interface
class Handler(Protocol):
    def handle(self, data: bytes) -> None: ...

def process(handler: Handler) -> None:
    handler.handle(data)

# Before: Any loses type information
def first(items: list[Any]) -> Any:
    return items[0]

# After: Generic preserves type
T = TypeVar("T")
def first(items: list[T]) -> T:
    return items[0]

# Before: Type checker doesn't understand the check
def process(data: str | dict[str, Any]) -> None:
    if isinstance(data, dict):
        # data still str | dict here without TypeGuard

# After: TypeGuard narrows the type
def is_dict_response(data: str | dict[str, Any]) -> TypeGuard[dict[str, Any]]:
    return isinstance(data, dict)

def process(data: str | dict[str, Any]) -> None:
    if is_dict_response(data):
        # data is dict[str, Any] here

# Before: Repeated complex type
def fetch(url: str) -> dict[str, str | int | list[str] | None]: ...
def parse(data: dict[str, str | int | list[str] | None]) -> Model: ...

# After: Named alias
JSONValue: TypeAlias = str | int | float | bool | None | list["JSONValue"] | dict[str, "JSONValue"]
APIResponse: TypeAlias = dict[str, JSONValue]

def fetch(url: str) -> APIResponse: ...
def parse(data: APIResponse) -> Model: ...

# Before: dict[str, Any]
def get_user() -> dict[str, Any]:
    return {"name": "Alice", "age": 30, "active": True}

# After: TypedDict defines shape
class User(TypedDict):
    name: str
    age: int
    active: bool

def get_user() -> User:
    return {"name": "Alice", "age": 30, "active": True}

# Before: Plain dict or untyped class
user = {"name": "Alice", "email": "alice@example.com"}

# After: Dataclass for internal data
@dataclass
class User:
    name: str
    email: str

# After: Pydantic for external/validated data
class UserInput(BaseModel):
    name: str
    email: EmailStr

## Modernization Plan

### Type System Changes

1. **Eliminate Any in api.py**
   - Line 23: response: Any → response: APIResponse (TypeAlias)
   - Line 45: callback: Any → callback: Callable[[Event], None]
   - Line 67: data: Any → data: UserData (TypedDict)

2. **Add Protocols for duck typing**
   - Create Handler protocol for plugin system
   - Create Serializable protocol for export functions

3. **Add Generics for containers**
   - Cache[T] generic class
   - Result[T, E] for error handling

### Library Migrations

1. **requests → httpx**
   - Files affected: api.py, client.py
   - Breaking changes: Session → Client, response.json() typing
   - Async opportunity: Yes

2. **json → orjson**
   - Files affected: serialization.py
   - Breaking changes: orjson.dumps returns bytes
   - Performance gain: ~10x

### Estimated Impact
- Files to modify: 12
- New type definitions: 8
- Breaking changes: 3 (internal only)

Task(
  agent="python-code-reviewer",
  prompt="Review the modernization plan at .claude/plans/stinkysnake-plan.md

REVIEW CRITERIA:

1. **Pythonic Best Practices**
   - Are the proposed patterns idiomatic Python?
   - Do they follow PEP guidelines?
   - Are simpler solutions available?

2. **Online Verification**
   - Verify type patterns against mypy/pyright docs
   - Check library recommendations against current best practices
   - Confirm version compatibility claims

3. **Feasibility Assessment**
   - Are the proposed changes realistic?
   - What is the effort vs benefit ratio?
   - Are there hidden dependencies?

4. **Breaking Change Analysis**
   - What interfaces change?
   - What downstream code is affected?
   - Is backward compatibility needed?

5. **Risk Assessment**
   - What could go wrong?
   - What tests are needed?
   - What rollback plan exists?

OUTPUT:
Create review report at .claude/reports/plan-review-{timestamp}.md with:
- Issues found (blocking, warning, suggestion)
- Verification results with sources
- Feasibility scores per change
- Breaking change inventory
- Recommended modifications"
)

## Plan Review Report

### Summary
- Blocking Issues: N
- Warnings: N
- Suggestions: N
- Overall Feasibility: High/Medium/Low

### Blocking Issues

#### Issue 1: Protocol misuse in Handler
**Location**: Plan section 2.1
**Problem**: Protocol used where ABC is more appropriate
**Evidence**: [link to mypy docs on Protocol vs ABC]
**Recommendation**: Use ABC with @abstractmethod

### Warnings

#### Warning 1: orjson bytes return
**Location**: Library migration section
**Risk**: Downstream code expects str from json.dumps
**Mitigation**: Add .decode() or update all callers

### Verification Results

| Claim | Verified | Source |
|-------|----------|--------|
| TypeGuard narrows in if blocks | ✓ | mypy docs |
| httpx is drop-in for requests | ✗ | API differs |
| orjson 10x faster | ✓ | benchmark link |

### Breaking Change Inventory

| Change | Affected Code | Severity |
|--------|--------------|----------|
| APIResponse type | 5 functions | Medium |
| httpx migration | 12 call sites | High |

### Recommended Modifications

1. Split httpx migration into separate PR
2. Add compatibility shim for json.dumps
3. Use ABC instead of Protocol for Handler

## Modernization Plan (Revised)

### Changes from Review

1. **Handler: Protocol → ABC**
   - Reason: Plugin system requires inheritance
   - Evidence: [reviewer's mypy docs link]

2. **httpx migration: Deferred**
   - Reason: High breaking change risk
   - Alternative: Create separate PR after core changes

3. **orjson: Added decode shim**
   - Added: compat.dumps() wrapper returning str

### Updated Implementation Order

1. Type aliases and TypedDicts (no breaking changes)
2. Protocol/ABC additions (additive)
3. Generic containers (additive)
4. Any elimination (may require caller updates)
5. [DEFERRED] httpx migration

# Find all documentation files
fd -e md -e rst -e txt . docs/ README.md CHANGELOG.md

# Find docstrings in affected files
uv run rg "^\s+\"\"\"" $ARGUMENTS

## Documentation Update Plan

### Files to Update

| Doc File | Section | Change Needed |
|----------|---------|---------------|
| README.md | Installation | Add orjson dependency |
| docs/api.md | fetch_data() | Update return type |
| CHANGELOG.md | Unreleased | Add type improvements |

### Docstrings to Update

| Code File | Function | Docstring Change |
|-----------|----------|------------------|
| api.py | fetch_data | Update return type docs |
| models.py | User | Add field descriptions |

### New Documentation Needed

- docs/types.md: Document TypeAliases
- docs/migration.md: Breaking change guide

# src/types.py
from typing import TypeAlias

JSONValue: TypeAlias = str | int | float | bool | None | list["JSONValue"] | dict[str, "JSONValue"]
APIResponse: TypeAlias = dict[str, JSONValue]

# src/protocols.py
from typing import Protocol

class Handler(Protocol):
    def handle(self, data: bytes) -> None: ...

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

# src/schemas.py
from typing import TypedDict, NotRequired

class UserData(TypedDict):
    name: str
    email: str
    age: NotRequired[int]

# src/models.py
from dataclasses import dataclass

@dataclass
class User:
    name: str
    email: str
    age: int | None = None

Task(
  agent="python-pytest-architect",
  prompt="Write failing tests for the interfaces defined in the modernization plan.

CONTEXT:
- Plan: .claude/plans/stinkysnake-plan.md
- Interfaces: src/types.py, src/protocols.py, src/schemas.py

REQUIREMENTS:

1. **Test Each Protocol**
   - Test that protocol can be satisfied
   - Test that non-conforming types are rejected
   - Test protocol runtime behavior if applicable

2. **Test Each TypedDict**
   - Test required keys
   - Test optional keys (NotRequired)
   - Test type validation

3. **Test Each Function Signature**
   - Test return type matches TypeAlias
   - Test parameter types
   - Test edge cases

4. **Test Behavioral Expectations**
   - Test that refactored code maintains behavior
   - Test error handling patterns
   - Test async behavior if applicable

OUTPUT:
- Create test files in tests/
- Tests MUST fail (implementations don't exist yet)
- Stop after tests are written
- Report test file locations"
)

# Run tests - they should fail
uv run pytest tests/ -v

# Expected output: X failed, 0 passed

/snakepolish $ARGUMENTS

# Final verification
uv run pytest tests/ -v
uv run mypy $ARGUMENTS --strict
uv run ruff check $ARGUMENTS

Skill(command: "holistic-linting")     # Linting workflows
Skill(command: "pre-commit")           # Git hooks
Skill(command: "modernpython")         # Python 3.11+ patterns
Skill(command: "python3-development")  # Core patterns

Task(agent="linting-root-cause-resolver", ...)  # Phase 1 linting
Task(agent="python-code-reviewer", ...)          # Phase 4 review
Task(agent="python-pytest-architect", ...)       # Phase 8 tests

/snakepolish  # Phase 9 implementation (context: fork)