Python Code Organizer

What Problem It Solves

Many Python projects start as scripts or experiment code, then quickly accumulate inconsistent naming, messy import statements, unclear directory responsibilities, and missing documentation. A blind refactor can easily overshoot: adding full test suites, configuration systems, or DDD layers to a handful of scripts usually makes the project harder to read.

This skill constrains the cleanup process into assess first, confirm twice, execute last, avoiding default execution of every possible optimization. It is not just an autoformatter; it proposes an approved maintenance plan based on project type and engineering goals.

How It Works

• Round one: strategy selection: it scans project scale, type, and main issues, then presents four levels: light cleanup, standard organization, deep refactor, and full refactor, with a recommendation and rationale.
• Round two: plan confirmation: it lists directory changes, file edits, deletions, new configuration, and documentation changes, then waits for explicit approval.
• Execution phase: depending on the selected strategy, it applies code formatting, naming conventions, import sorting, type annotations, comment standards, dead-code cleanup, configuration parameterization, or test coverage.
• Documentation generation: it produces README.md, CHANGELOG.md, and NOTE.md at a level of detail matched to the strategy, covering users, change tracking, and quick personal reference.

For deep learning projects, it prioritizes models/, data/, experiments/, hyperparameter configuration, and logging. For Web/API projects, it focuses on routing, middleware, and authentication boundaries. For CLI or data pipelines, it emphasizes centralized configuration, logging, and progress feedback.

Where It Fits

This skill is most useful for maintainable Python projects, especially prototype tools, data processing scripts, small services, and publishable libraries. It is not intended for aggressive best-practice enforcement: if the goal is only to run an experiment, light or standard organization is usually enough. Deep or full refactoring makes sense when the project needs team collaboration, release, or long-term maintenance. Execution still depends on user approval, so it should not delete files or restructure the project without confirmation.