python-typing

name	python-typing
description	Migrate Python codebases to strict type checking with pyright. Use when user wants to add types, fix type errors, set up strict mode, or run a typing migration. Provides setup automation, fix patterns, discipline enforcement, and optional iteration loop support.

Python Typing

Migrate Python codebases to strict type checking using pyright.

Onboarding

On first invocation, run the setup flow:

1. Determine Strictness Level

If user explicitly said "strict typing", use strict. Otherwise ask:

What level of type checking?
  A) strict - Maximum type safety (recommended for new projects)
  B) standard - Balanced (recommended for existing codebases)
  C) basic - Minimal, just obvious bugs

Run pyright at each level to show baselines:

npx pyright --outputjson 2>/dev/null | jq '.summary.errorCount' # strict
npx pyright -p pyrightconfig-standard.json --outputjson 2>/dev/null | jq '.summary.errorCount'

2. Choose Setup Type

Setup options:
  A) Recommended - Full setup with tracking and rules
  B) Minimal - Just pyright config and rules
  C) Custom - Choose each component

3. Run Setup

For Recommended (A):

python3 <SKILL_PATH>/scripts/init_typing.py --level {strict|standard|basic} --full

This installs:

• pyrightconfig-{level}.json
• .long-task-harness/ with typing rules
• typing-findings.md
• Pre-commit hook
• long-task-harness (if not present)
• ralph-wiggum plugin (Claude Code only)

For Minimal (B):

python3 <SKILL_PATH>/scripts/init_typing.py --level {strict|standard|basic}

For Custom (C): Ask which components, then run with appropriate flags.

4. Explain What Was Installed

After setup, explain each component:

• What pyrightconfig does
• What the rules enforce and why
• What long-task-harness provides (link to docs)
• How ralph-wiggum works (if installed)

5. Show Fix Strategy

Recommended approach - fix in layers:

1. Quick wins: unused imports, missing return types, generic args
2. Annotations: parameter types, class attributes
3. Type safety: None checks, narrowing, unions
4. Structural: conditional imports, TypedDict, Protocol
5. External: missing stubs, third-party workarounds
6. Edge cases: complex generics, metaprogramming

Run analysis first:
  python3 <SKILL_PATH>/scripts/analyze_typing.py

6. Offer Iteration Loop (if ralph-wiggum installed)

Show the prompt template and confirm before user runs it.

---

Fixing Errors

Workflow

1. Run npx pyright to see current errors
2. Pick 5-10 related errors (same file or type)
3. Fix properly (no shortcuts)
4. Run pyright to verify
5. Commit with descriptive message
6. Repeat

Rules (Critical)

1. No # type: ignore - Fix the actual issue. If truly unfixable, document in typing-findings.md first.

2. No assert x is not None - Use proper patterns:

   • Early return: if x is None: return
   • Conditional: if x is not None: x.method()
   • Raise with context: if x is None: raise ValueError("x required")

3. Avoid Any - Use specific types, TypeVar, Union, Protocol, or object.

4. Avoid cast() - Use isinstance() narrowing or TypeGuard.

Common Patterns

See references/patterns.md for detailed fix patterns:

• Conditional imports (try/except)
• TypedDict for dict shapes
• Protocol for duck typing
• Third-party stubs
• Complex generics

When Stuck

1. Check patterns.md for similar issues
2. Check typing-findings.md for documented workarounds
3. For third-party libs: install stubs or document limitation
4. Ask for help rather than using type:ignore

---

Progress Tracking

With long-task-harness

Update .long-task-harness/long-task-progress.md with:

• Error count at start/end of session
• Files/modules fixed
• Patterns discovered
• Decisions made

Every 50 Errors

• Review work for consistency
• Document new patterns in typing-findings.md
• Note any recurring issues

---

Ralph-Wiggum Loop

For unattended iteration (Claude Code only):

/ralph-loop "Fix pyright strict mode errors.

## Setup
Run: npx pyright
Baseline: {ERROR_COUNT} errors

## Rules (CRITICAL)
1. Do NOT use # type: ignore - fix the actual issue
2. Do NOT use assert x is not None - use proper conditionals
3. Avoid Any - use specific types
4. Avoid cast() - use isinstance() narrowing

## Workflow
1. Run pyright, note error count
2. Pick 5-10 related errors (same file or same type)
3. Fix them properly
4. Run pyright to verify
5. Commit with descriptive message
6. Repeat

## Every 50 Errors
- Review for consistency
- Document unfixable issues in typing-findings.md
- Note patterns

## If Stuck
- Check typing-findings.md for similar issues
- For third-party libs: document and use minimal workaround
- Ask for help rather than using type: ignore

## Completion
When pyright reports 0 errors: <promise>TYPING_COMPLETE</promise>" --completion-promise "TYPING_COMPLETE" --max-iterations 300

---

References

• references/patterns.md - Common fix patterns by category
• references/faq.md - Detailed FAQ for common questions