# Annotations

> Workflow for adding type annotations to Plain packages. Use this when adding or improving type coverage.

- Skill: `diegosouzapw/annotations` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/annotations`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/annotations/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/annotations

---


# Type Annotation Workflow

We are gradually adding type annotations using Python 3.13+.

## Workflow

1. **Check current coverage**:

    ```
    uv run plain code annotations <directory> --details
    ```

2. **Add annotations**: Focus on function/method signatures (parameters and return types)

3. **Type check**:

    ```
    ./scripts/type-check <directory>
    ```

4. **Format**: `./scripts/fix`

5. **Test**: `./scripts/test <package>`

6. **Verify improvement**:

    ```
    uv run plain code annotations <directory>
    ```

7. **Add to validation**: Once a directory reaches 100% coverage, add it to `FULLY_TYPED_PATHS` in `scripts/type-validate`

## Guidelines

- Add `from __future__ import annotations` when necessary
- Focus on public APIs and user-facing methods first
- Don't annotate `__init__` return types (type checkers infer `None`)
- Use explicit `return None` for functions with `-> Type | None` return type
- Some Django-style ORM patterns are inherently difficult to type - that's okay
- Goal is progress, not perfection

## Example

```bash
# Check coverage
uv run plain code annotations plain/plain/assets --details

# After adding annotations...
./scripts/type-check plain/plain/assets
./scripts/fix
./scripts/test plain
uv run plain code annotations plain/plain/assets  # Should show 100%
```