Refactor a 3000-line Python CLI module into smaller files
Session from clean-slides-sessions on Hugging Face by thomasmustier · MIT · condensed by Coders Talk
Review the clean-slides Python codebase for maintainability issues, then incrementally split the 3000+ line cli.py module into focused submodules without breaking behavior, alongside parallel chart-engine work by the developer.
- +0Prompt · +0Review the codebase for code quality and maintainability. What's driving complexity? Focus on major levers to simplify so we can keep building. Write findings to a .md
- +0mAgent did · +0mExplored the codebase (LOC counts, ruff C901 complexity, pyright, tests, module dependency graph) and wrote a code-quality-maintainability-review.md identifying cli.py as the dominant complexity hotspot along with duplicated validation logic.
- +9mPrompt · +9mPlease do it. Note: not concerned with backward compatibility, this is pre-release so major changes are fine. Be aware chart_generator/chart_render/charts.py are under parallel refactor — start with cli.py.
- Break · 55m away, not counted
- +11mAgent did · +11mSplit cli.py incrementally: extracted spec_pipeline.py, template_init_config.py, cli_parser.py, cli_text.py, cli_common.py, cli_inspect.py, verifying with ruff/pyright/pytest after each extraction, avoiding files touched by parallel chart work.
- +12mIntervention · +12mTold the agent not to restore any unexpected changes it sees in the repo, since those are from parallel chart work happening on the same branch.Why: I didn't want it stepping on the other refactor happening in parallel — those files aren't mine to touch right now.
- +34mPrompt · +34mGreat please commit your changes incrementally and keep going
- +34mAgent did · +34mContinued extracting cli_deck.py, cli_render.py, cli_project.py, cli_spec_commands.py, cli_template.py, cli_generate.py, cli_edit.py, simplifying cli_text.py further, and committing each step after ruff/pyright/pytest passed — shrinking cli.py from ~3000 to ~120 lines across ~11 commits.
- +2h 2mPrompt · +2h 2mPlease push your refactor commits to a different branch and open a PR, without impacting my ongoing parallel work
- +2h 2mAgent did · +2h 2mCreated a separate git worktree from origin/main, cherry-picked the refactor commits, fixed a chart module-path resolution issue, pushed refactor/cli-modularization, and opened PR #16.
- +2h 15mIntervention · +2h 15mReviewed the bot's PR comment flagging that --module-path support had been dropped in the refactor and decided it must be restored since it's a functional regression, not an intended change.Why: This was meant to be a pure refactor with no behavior change, so dropping a working flag was a regression I had to catch and reverse.
- +2h 23mOutcome · +2h 23mPR #16 merged into main after CI went green; cli.py reduced from ~3000 lines to ~120 lines split across ~12 new focused modules, all tests and pyright/ruff checks passing, parallel branch work left untouched.
Next time I'd open with the parallel-work caveat up front — telling it about the concurrent chart-engine branch early saved a lot of back-and-forth about which files were safe to touch. The intervention that mattered most was catching the dropped --module-path flag from the PR review; without that, a 'pure refactor' would have shipped a silent regression. Splitting into a separate worktree/branch for the PR was the right call to keep my in-progress local changes untouched while still getting the refactor reviewed and merged.