refactor-module-stutter

Audit Python modules for namespace-repeating public symbols and generate Markdown reports.

6|1|Updated Jan 5, 2026

Search Tags:#api #python #refactor #static-analysis #lint #naming #module-stutter

Ready to run

npx skills add https://github.com/JordanGunn/skills --skill refactor-module-stutter

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: refactor-module-stutter
Source: https://github.com/JordanGunn/skills/tree/main/skills/refactor/module-stutter
Command: npx skills add https://github.com/JordanGunn/skills --skill refactor-module-stutter

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

Public Python APIs often expose symbols that redundantly repeat the module name (e.g., a module named fragment exporting WriteFragment). This pattern adds noise and harms readability, maintainability, and import ergonomics.

Core Features & Use Cases

Detect module-name stutter in top-level classes and functions, including re-exports declared in init.py.
Generate a concise Markdown report with recommended renames and safe refactor paths, suitable for CI gating.
Configurable exclusions via ignore rules to adapt to large codebases and gradual migrations.

Quick Start

Install and run the checker against your Python package to surface stutter findings and suggested fixes.

Frequently Asked Questions about refactor-module-stutter

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

What is module-name stutter in Python APIs?▼

Module-name stutter in Python APIs occurs when public symbols redundantly repeat the module namespace, such as a module named fragment exporting a class named WriteFragment. This pattern adds noise and harms code readability, maintainability, and import ergonomics.

How do I detect redundant module name repetition in Python packages?▼

You detect redundant module name repetition by running a static-analysis audit against your Python package. The audit checks top-level class and function definitions, including __init__.py re-exports, to surface symbols that repeat the module namespace.

Can I configure ignore lists for Python naming lint rules in large codebases?▼

Yes, you can configure ignore lists for naming lint rules to adapt to large codebases. This allows for gradual migrations by excluding specific symbols or modules from the stutter detection audit.

How do I enforce Python API naming conventions in CI pipelines?▼

You enforce Python API naming conventions in CI pipelines by using the stutter audit's gate enforcement feature. The audit produces a Markdown report with findings and recommended refactor steps, which can block pipeline progression on violations.

What is the best way to refactor Python __init__ exports to remove namespace stutter?▼

The best way to refactor Python __init__ exports is to follow the suggested renames and safe refactor paths generated in the Markdown report. This ensures re-exported symbols drop the redundant module namespace without breaking the public API.