refactor-import-hygiene

Audit Python imports to preserve semantic context and prevent shadowing after refactors.Prefer namespace-first imports over direct symbol imports for generic identifiers.

⭐5stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026

When & Why to Use This Skill

The refactor-import-hygiene skill is a specialized tool for Python developers designed to maintain high code quality during refactoring. It audits import statements to prevent identifier shadowing and ensures semantic clarity by prioritizing namespace-first imports. By automating the detection of ambiguous symbols and 'module-stutter,' it helps maintain a clean, professional, and bug-free codebase.

Use Cases

  • Large-scale Refactoring: Automatically auditing and updating imports when moving code between namespaces to prevent name collisions.
  • Code Quality Enforcement: Ensuring that generic identifiers like 'Metadata', 'Spec', or 'Payload' do not shadow local variables or other imports.
  • Standardizing Import Styles: Transitioning a project from 'from X import Y' to namespace-first imports to improve code readability and context.
  • Pre-merge Audits: Using the skill during the code review process to identify potential import-related bugs before they reach production.
namerefactor-import-hygiene
licenseMIT
description|
authorJordan Godau

Instructions

Read all references in references/ before using this skill.

Signals

  • Module-stutter was removed and symbols became intentionally generic (Metadata, Spec, File, Header, Payload)
  • A refactor moved code into new namespaces and callsites were updated
  • The diff introduces many from X import Y imports
  • There are repeated name collisions or ambiguous identifiers in local scopes

References

Directory: references/

  • 01_GOAL.md
  • 02_DEFINITION.md
  • 03_RULES.md
  • 04_PROCEDURE.md
  • 05_OUTPUT.md
  • 06_EXAMPLES.md