feat: add --plan for guided refactoring workflow

[cheickmec]

What does this PR do?

Adds --plan CLI flag that generates a phased refactoring plan. Groups 56 rules into 9 ordered phases with dependency chains, auto-selects strategy (local_first vs architecture_first based on findings distribution), and outputs ready-to-use --select commands for each phase. Updates SKILL.md with comprehensive guided refactoring workflow.

Type of change

• New smell check
• CLI / output improvement
• Other feature

Checklist

• pytest tests/ -v passes
• New check has a test in tests/test_detector.py
• smellcheck src/smellcheck/ self-check runs clean (or new findings are intentional)
• No dependencies added (stdlib only)
• Commit messages follow Conventional Commits

For new smell checks

N/A — this is a CLI feature, not a new smell check.

Test plan

• 12 new tests covering phase coverage, rule mapping, plan computation, text/JSON formatting, strategy selection, skip logic, internal order, baseline integration, and 2 CLI E2E tests
• Full test suite passes (179/179)
• Self-check clean (smellcheck src/smellcheck/ --min-severity warning)
• --plan text output verified with sample code
• --plan --format json output validated with json.tool
• Vendor parity test passes

Additional context

• Composable with existing flags: --baseline, --select/--ignore, --diff, --scope, --format json
• Under architecture_first strategy, the phase 8→6 feedback relationship correctly renders as "Feeds into" (forward flow) rather than "Feedback to" (loop)
• skip_if was intentionally omitted from phase defs — phases skip naturally when they have 0 findings

🤖 Generated with Claude Code

[github-actions]

❌ PR Template Validation FailedNo template marker found in the PR body.Please use one of the available templates when creating your PR:

• bugfix
• docs
• feature

Tip: Add ?template=bugfix.md to the PR creation URL, or select a template from the dropdown.

[Copilot]

Pull request overview

This PR adds a --plan CLI flag that generates a customized, phased refactoring plan based on actual code findings. The feature groups smellcheck's 56 rules into 9 ordered phases (correctness, dead code, clarity, idioms, control flow, functions, state/class design, architecture, and OO metrics) with dependency chains and execution metadata. The plan auto-selects between local_first (default, phases 0-8) and architecture_first (reordered to [0,1,7,8,2,3,4,5,6]) strategies based on the ratio of cross-file/metric findings (>30% threshold). The implementation is fully composable with existing flags like --baseline, --select, --diff, and --format json.

Changes:

• Added refactoring phase metadata structure (_REFACTORING_PHASES) organizing 56 rules into 9 phases with execution mode, internal ordering chains, gates, rescan flags, and feedback loops
• Implemented plan computation logic (_compute_plan, _group_findings_by_phase) with automatic strategy selection based on findings distribution
• Added text and JSON formatters for plan output
• Integrated --plan flag into CLI with proper help text and examples
• Provided 12 comprehensive tests covering phase coverage, mapping, strategy selection, formatting, and CLI integration
• Updated SKILL.md with detailed guided refactoring workflow documentation including 3-pass phase execution, manual pattern assignments, conditional branching, and feedback loops

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/smellcheck/detector.py	Core implementation: phase definitions, plan computation, formatters, CLI integration
plugins/python-refactoring/skills/python-refactoring/scripts/smellcheck/detector.py	Vendored copy synced with src/ changes
tests/test_detector.py	12 new tests for phase coverage, strategy selection, formatting, and CLI E2E
plugins/python-refactoring/skills/python-refactoring/SKILL.md	Comprehensive guided workflow documentation replacing old workflow section
README.md	Added --plan usage examples

Comments suppressed due to low confidence (4)

src/smellcheck/detector.py:499

• Extra blank line inconsistent with other phase definitions. All other phases have no blank line before "feedback_to". Remove this line to maintain consistent formatting.
  src/smellcheck/detector.py:527
• Extra blank line inconsistent with other phase definitions. All other phases have no blank line before "feedback_to". Remove this line to maintain consistent formatting.
  plugins/python-refactoring/skills/python-refactoring/scripts/smellcheck/detector.py:499
• Extra blank line inconsistent with other phase definitions. All other phases have no blank line before "feedback_to". Remove this line to maintain consistent formatting.
  plugins/python-refactoring/skills/python-refactoring/scripts/smellcheck/detector.py:527
• Extra blank line inconsistent with other phase definitions. All other phases have no blank line before "feedback_to". Remove this line to maintain consistent formatting.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.