refactor-module-stutter

JordanGunn's avatarfrom JordanGunn

Detect module/package name stutter in Python public APIs.Produces a Markdown report and optional CI gate.

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

When & Why to Use This Skill

This Claude skill automates the detection of 'name stuttering' in Python public APIs, identifying redundant patterns where module or package names are unnecessarily repeated in class or function identifiers. By providing AST-based analysis and Pylint integration, it helps developers maintain idiomatic Python codebases, improves API readability, and enforces professional naming conventions through automated reports and CI/CD gates.

Use Cases

  • API Design Audit: Automatically reviewing public-facing symbols in a new Python library to ensure names are concise and free of redundant prefixes before a public release.
  • Continuous Integration Gate: Integrating the Pylint plugin into CI/CD pipelines to block pull requests that introduce naming stutter, ensuring long-term codebase consistency.
  • Legacy Code Refactoring: Scanning large-scale Python projects to identify and document technical debt related to redundant naming, providing a roadmap for API cleanup and modernization.
namerefactor-module-stutter
licenseMIT
description|
authorJordan Godau

Instructions

Read all references in references/ before using this skill.

Signals

  • Reviewing new modules or public symbols
  • Auditing naming conventions before a release
  • The user asks to "check for stutter" or "audit naming"

References

Directory: references/

  • 01_GOAL.md
  • 02_DEFINITION.md
  • 03_RULES.md
  • 04_ENFORCEMENT.md
  • 05_CONFIGURATIONS.md
  • 06_OUTPUT.md
  • 07_SUGGESTIONS.md
  • 08_EXAMPLES.md

Scripts

Directory: scripts/

  • checker.py: AST-based checker + report
  • pylint.py: Pylint plugin that provides lint-level enforcement.