python-refactor

Python Refactoring

CRITICAL RULES

1. Execute phases in order. Analysis -> Planning -> Approval -> Execution -> Validation.
2. Write output files. Each phase writes to .python-refactor/ for persistence and context.
3. Stop at checkpoint. Get user approval of the refactoring plan BEFORE making any code changes.
4. Run tests after every change. Never proceed if tests fail.
5. Never enter plan mode. Execute immediately.
6. One pattern at a time. Don't combine multiple refactorings in a single edit.

Pre-flight

1. Check for existing session

Check if .python-refactor/state.json exists:

• If in progress: offer to resume or start fresh
• If complete: offer to archive and start fresh

2. Initialize state

Create .python-refactor/ directory and state.json:

{
  "target": "$ARGUMENTS",
  "status": "in_progress",
  "flags": {
    "strict_mode": false
  },
  "current_phase": 1,
  "completed_phases": [],
  "files_created": [],
  "started_at": "ISO_TIMESTAMP"
}

Phase 1: Analysis

1. Read the target code to understand current structure

2. Run complexity metrics (if available):

   uv run python ${CLAUDE_PLUGIN_ROOT}/skills/python-refactor/scripts/measure_complexity.py $ARGUMENTS 2>/dev/null
   uv run python ${CLAUDE_PLUGIN_ROOT}/skills/python-refactor/scripts/analyze_with_flake8.py $ARGUMENTS 2>/dev/null
   

   If scripts aren't available, analyze manually by reading the code.

3. Identify issues against thresholds:

   • Cyclomatic complexity: >10 per function (high priority)
   • Cognitive complexity: >15 per function (high priority)
   • Function length: >30 lines (medium priority)
   • Nesting depth: >3 levels (medium priority)

4. Establish test baseline:

   pytest [test files] -v 2>/dev/null || python -m pytest -v 2>/dev/null
   

   Record which tests exist and their pass/fail status.

Output file: .python-refactor/01-analysis.md

# Phase 1: Analysis

## Target
[file/directory path]

## Current Metrics
| Metric | Value | Threshold | Status |
|--------|-------|-----------|--------|
| Cyclomatic Complexity (avg) | X | <10 | PASS/FAIL |
| Cognitive Complexity (max) | X | <15 | PASS/FAIL |
| Max Function Length | X lines | <30 | PASS/FAIL |
| Max Nesting Depth | X | <=3 | PASS/FAIL |

## Issues Found
[Ordered by severity: HIGH, MEDIUM, LOW]

## Test Baseline
- Tests found: [count]
- Passing: [count]
- Failing: [count]