oe-lsp-pyright-refactor

shami-ah 的头像作者 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.

📖 中文导读: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. 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: oe-lsp-pyright-refactor description: 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.

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.