Skip to content

SKILL.md

Latest commit

 

History

History
165 lines (128 loc) · 4.74 KB

SKILL.md

File metadata and controls

165 lines (128 loc) · 4.74 KB
name py-refactor
description Orchestrate comprehensive Python refactoring - coordinates security, complexity, testing, code health, and modernization skills to systematically improve code quality.
status stable

Python Refactoring Orchestrator

Comprehensive refactoring workflow coordinating specialized skills to improve Python code quality.

Overview

This skill orchestrates multiple focused skills to perform systematic refactoring:

Skill Purpose Status
py-security Vulnerability detection and remediation stable
py-code-health Dead code and duplication removal stable
py-complexity Reduce cyclomatic/cognitive complexity stable
py-test-quality Coverage analysis and mutation testing stable
py-modernize Upgrade tooling and syntax stable
py-quality-setup Configure linters and type checkers stable
py-git-hooks Set up pre-commit hooks stable

Refactoring Priorities

Follow this impact-based prioritization:

  1. Critical: Security vulnerabilities (use py-security)
  2. High: Code duplication, untested code (<80% coverage)
  3. Medium: Complexity reduction, dead code removal
  4. Low: Syntax modernization, style improvements

Standard Refactoring Workflow

Phase 1: Setup (if needed)

1. If quality tools not configured (pyproject.toml):
   → Invoke: py-quality-setup
   (also configures .claude/settings.local.json permissions for all tools)

2. Add analysis tools to [dependency-groups] dev in pyproject.toml:
   "radon", "vulture", "pylint", "bandit", "lizard",
   "pytest-cov", "mutmut", "wily", "ruff", "mypy", "basedpyright"

3. Install and activate:
   uv sync && source .venv/bin/activate

Phase 2: Comprehensive Analysis

Run all automated scanners to get baseline:

mkdir -p reports

# Security
ruff check . --select S > reports/security.txt
bandit -r . -f json -o reports/security.json

# Code health
vulture . --min-confidence 80 > reports/dead_code.txt
pylint --disable=all --enable=duplicate-code --recursive=y . > reports/duplication.txt

# Complexity
radon cc . -n C -s > reports/complexity.txt
lizard -l python -w > reports/cognitive_complexity.txt
radon mi . -n B > reports/maintainability.txt

# Test quality
pytest --cov=. --cov-report=html --cov-report=term > reports/coverage.txt

# Initialize complexity tracking
wily build .

Phase 3: Prioritized Remediation

Step 1: Security (Critical)

If security.txt shows issues:
→ Invoke: py-security
   - Fix SQL injection, hardcoded secrets, weak crypto
   - Verify: ruff check . --select S (clean)
   - Run tests to ensure no regressions

Step 2: Test Quality (High - enables safe refactoring)

If coverage < 80%:
→ Invoke: py-test-quality
   - Write tests for untested code
   - Run mutation testing to verify test quality
   - Target: ≥80% coverage, ≥75% mutation score

Step 3: Code Health (High)

If duplication.txt or dead_code.txt show issues:
→ Invoke: py-code-health
   - Remove dead code (vulture findings)
   - Consolidate duplicates (pylint findings)
   - Verify: Tests still pass, coverage maintained

Step 4: Complexity Reduction (Medium)

If complexity.txt shows C+ functions or maintainability < 65:
→ Invoke: py-complexity
   - Extract functions, simplify conditionals
   - Use guard clauses, lookup tables
   - Track improvement with wily
   - Verify: radon cc . -n C (clean)

Step 5: Modernization (Optional)

If project uses old patterns or pip:
→ Invoke: py-modernize
   - Migrate pip → uv
   - Upgrade syntax to Python 3.13+
   - Consolidate to pyproject.toml
   - Verify: Tests pass, type checking works

Phase 4: Automation

Set up git hooks to prevent regressions:
→ Invoke: py-git-hooks
   - Pre-commit hooks run ruff, mypy, basedpyright
   - Optionally add security checks (bandit)
   - Test hook works correctly

Phase 5: Final Validation

# Run complete validation suite
ruff check .
mypy . && basedpyright .
ruff check . --select S
radon cc . -n C
vulture . --min-confidence 80
pytest --cov=. --cov-fail-under=80

# Track overall improvement
wily diff HEAD~1
wily report .

When NOT to Use This Skill

Don't use orchestrated refactoring when:

  • Single focused task: Use specific skill directly (e.g., just py-security for CVE fix)
  • No tests exist: Write tests first (py-test-quality), then refactor
  • Active development: Coordinate with team to avoid merge conflicts
  • Production incident: Fix incident first, refactor later

Additional Resources

  • WORKFLOWS.md: Quick workflows for specific scenarios (security sweep, complexity sprint, legacy modernization)
  • METRICS.md: Success metrics, tool reference, Engineering Charter alignment