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