---
type: skill
domain: development
links: [Corpus_Callosum/CONSTITUTION.md, PULSE_OS.md]
---

# TYPE_TITAN.md
> **ROLE:** TYPING SPECIALIST
> **TRIGGER:** "INTERFACE"

## Protocol

1. **Audit current type coverage.** Run `mypy --strict <module>` or `pyright` for Python. Run `tsc --noEmit --strict` for TypeScript. Record error count as baseline.
2. **Annotate all function signatures.** Every function gets param types and return type. No exceptions. Use `-> None` explicitly, never omit return types.
3. **Replace weak types.** Ban `Any`, `object`, `dict` without generics. Use `TypedDict` for JSON schemas, `Protocol` for duck typing, `Union`/`Literal` for constrained values.
4. **Add runtime validation at boundaries.** Use Pydantic `BaseModel` or `dataclasses` for external input (API, JSON files, env vars). Trust nothing from outside.
5. **Configure strict mode permanently.** Add `mypy.ini` or `pyproject.toml` with strict settings. Add type checking to CI. Block merges on type errors.

## Metrics & Thresholds
- **Type coverage:** >95% of functions fully annotated (params + return)
- **`Any` usage:** 0 in new code, <5 total in legacy (with tracked issues to fix)
- **mypy/pyright errors:** 0 on `--strict` for all modified files
- **Pydantic models:** 100% of external JSON schemas have a model

## Good Example
```python
# mypy.ini
[mypy]
strict = True
disallow_any_explicit = True
warn_return_any = True

# Code
from typing import TypedDict

class TaskRecord(TypedDict):
    task_id: str
    status: str  # "open" | "claimed" | "done"
    tier: str

def claim_task(board: list[TaskRecord], agent: str) -> TaskRecord | None:
    """Claim the first open task matching agent tier."""
    for task in board:
        if task["status"] == "open":
            task["status"] = "claimed"
            return task
    return None
```

## Anti-Patterns
- **`Any` as escape hatch:** Using `Any` to silence errors instead of fixing the type. Every `Any` is a hidden bug.
- **Type-only, no validation:** Annotating `data: dict[str, str]` but never validating the actual JSON. Types lie at runtime; Pydantic doesn't.
- **Ignoring generics:** Using bare `list`, `dict`, `set` without type params. Always specify: `list[str]`, `dict[str, int]`.

## Tools
- `python Autonomic_System/Utilities/Tools/brain_query.py --query "type errors in <module>"`
- `python Autonomic_System/Utilities/Tools/pulse_save.py --agent <you> --learnings "typed <module>, 0 mypy errors"`
- `python Autonomic_System/Utilities/Tools/pulse_relay.py --tasks "Type annotate <module>:development:fast"`

## Verification Checklist
- [ ] `mypy --strict` passes with 0 errors on all modified files
- [ ] No bare `Any` in new or modified code
- [ ] All external data parsed through Pydantic/TypedDict
- [ ] Return types explicit on every function (including `-> None`)
- [ ] CI blocks merges on type check failures
