oe-lsp-pyright-refactor

shami-ah's avatarfrom shami-ah

Refactor planning and execution discipline using LSP/Pyright. Use when making non-trivial refactors (splitting files, renaming symbols, moving modules) and you want compiler-accurate references/definitions, plus a Pyright-driven contract baseline to avoid regressions.

⭐0stars🔀1forks📁View on GitHub🕐Updated Jan 8, 2026
[Developer Tools]

When & Why to Use This Skill

This Claude skill streamlines complex code refactoring by integrating LSP (Language Server Protocol) and Pyright static analysis into the agent's workflow. It solves the problem of 'blind' refactoring—where AI might miss hidden dependencies or break type contracts—by providing compiler-accurate symbol tracking and real-time diagnostic feedback. This ensures that structural changes like module migrations and symbol renames are executed with high precision and zero regressions.

Use Cases

  • Large-scale Symbol Renaming: Safely rename classes, methods, or variables across multiple files with 100% accuracy by using LSP to find all definitions and references.
  • Module Restructuring and File Splitting: Move modules or decompose monolithic files while automatically identifying and updating all affected import statements and dynamic dependencies.
  • Type-Safe Interface Hardening: Replace 'stringly-typed' payloads or loose dictionaries with formal Protocols and TypedDicts, using Pyright to instantly catch missing attributes or type mismatches.
  • Incremental API Migration: Implement a 'shim-first' strategy to keep public surfaces stable using re-exports and thin wrappers while internal logic is being reorganized.
  • Regression Detection: Use Pyright-driven contract baselines after each refactoring step to identify Optional leaks, incorrect return types, or broken interface implementations.
nameoe-lsp-pyright-refactor
descriptionRefactor planning and execution discipline using LSP/Pyright. Use when making non-trivial refactors (splitting files, renaming symbols, moving modules) and you want compiler-accurate references/definitions, plus a Pyright-driven contract baseline to avoid regressions.

oe-lsp-pyright-refactor

Workflow (shim-first, LSP-first)

  1. Before changes:

    • Use LSP to find the definition, outgoing calls, and references for the symbols you will move/rename.
    • Inventory importers before moving modules (including dynamic imports).

  2. During refactor:

    • Keep public surfaces stable with re-exports/thin wrappers first.
    • Prefer moving pure helpers/constants before orchestration.

  3. After each PR-sized step:

    • Use Pyright/LSP diagnostics to catch Optional leaks, wrong return types, and missing attributes.
    • Fix the contract at the boundary (Protocol/TypedDict) rather than sprinkling Any.

Canonical plans

  • Use docs/internal/BACKEND_REFACTORING_PLAN_DEC_2025.md for step-file ladders and preserve sets.
  • Use docs/internal/BACKEND_REFACTORING_PLAN_DEC_2025_ADDENDUM.md for production hardening + PH5 typing work.

Common refactor targets (Pyright tends to catch first)

  • Adapter interfaces: define Protocols for optional capabilities instead of hasattr-only contracts.
  • API boundary models: ensure required fields never receive None (or model them as Optional intentionally).
  • “stringly typed” payloads: introduce TypedDicts for event_entry, draft_messages, process_msg output.