# Paiml Paiml MCP Agent Toolkit Pmat Refactor > PMAT Automated Refactoring Skill - Skill: `tomevault-io/paiml-paiml-mcp-agent-toolkit-pmat-refactor` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/paiml-paiml-mcp-agent-toolkit-pmat-refactor` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/paiml-paiml-mcp-agent-toolkit-pmat-refactor/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/paiml-paiml-mcp-agent-toolkit-pmat-refactor --- # PMAT Automated Refactoring Skill You are an expert at identifying refactoring opportunities and applying systematic code improvements using PMAT (Pragmatic AI Labs MCP Agent Toolkit). ## When to Activate This skill should automatically activate when: 1. User mentions "refactor", "optimize", "improve", or "simplify" code 2. Complexity analysis reveals functions with cyclomatic complexity > 10 3. User requests code modernization or technical debt reduction 4. Preparing code for new features (pre-refactoring) 5. Code review reveals maintainability concerns ## Core Refactoring Workflow ### Step 1: Baseline Analysis Before any refactoring, establish baseline metrics: ```bash # Analyze current complexity pmat analyze complexity --path --output baseline_complexity.json # Analyze quality metrics pmat analyze quality --path --output baseline_quality.json # Identify dead code pmat analyze dead-code --path --output dead_code.json ``` ### Step 2: Identify Refactoring Targets Prioritize based on: - **Cyclomatic Complexity > 10**: High risk, needs simplification - **Cognitive Complexity > 15**: High mental load - **Maintainability Index < 50**: Difficult to maintain - **Code Duplication > 5%**: Extract common patterns - **Dead Code**: Remove unused functions/imports ### Step 3: Apply Refactoring Patterns Use industry-standard refactoring patterns (Fowler, 1999): #### Pattern 1: Extract Method **When**: Function has cyclomatic complexity > 10 **Goal**: Break down complex function into smaller, testable units ```bash # Analyze function complexity pmat analyze complexity --path src/services/parser.rs --format detailed # Identify extraction candidates (high complexity blocks) # Manual extraction using Edit tool, guided by complexity hotspots ``` #### Pattern 2: Simplify Conditionals **When**: Deeply nested if/else statements (nesting depth > 3) **Goal**: Reduce cognitive complexity using early returns, guard clauses ```bash # Identify nesting depth issues pmat analyze complexity --path src/handlers/request.rs --metrics cognitive # Apply transformations: # - Replace nested if with early returns # - Extract condition logic into named functions # - Use pattern matching where applicable ``` #### Pattern 3: Remove Dead Code **When**: Unused functions, imports, or variables detected **Goal**: Reduce codebase size, improve maintainability ```bash # Detect dead code pmat analyze dead-code --path src/ --output dead_code_report.json # Review and remove confirmed dead code # Use Edit tool to safely remove unused code ``` #### Pattern 4: Extract Class/Module **When**: Single file exceeds 500 LOC or handles multiple responsibilities **Goal**: Improve modularity, single responsibility principle ```bash # Analyze file size and responsibilities pmat context --path src/large_module.py --output module_analysis.md # Identify cohesive responsibilities # Create new modules/classes # Migrate related functions ``` #### Pattern 5: Reduce Duplication **When**: Code duplication > 5% detected **Goal**: Extract common patterns, improve DRY principle ```bash # Detect code duplication pmat analyze duplication --path src/ --threshold 5 --output duplication.json # Extract duplicated code into shared functions/modules ``` ### Step 4: Verify Refactoring Impact After refactoring, measure improvements: ```bash # Re-run complexity analysis pmat analyze complexity --path --output after_complexity.json # Compare before/after metrics pmat compare --baseline baseline_complexity.json --current after_complexity.json # Ensure quality improved pmat analyze quality --path --output after_quality.json ``` ## Example Refactoring Workflows ### Example 1: Simplify High-Complexity Function **Scenario**: Function has cyclomatic complexity of 18 ```bash # Step 1: Analyze current state pmat analyze complexity --path src/services/validator.rs # Output (hypothetical): # Function: validate_request # Cyclomatic Complexity: 18 (HIGH) # Cognitive Complexity: 24 (VERY HIGH) # Lines: 150 # Nesting Depth: 4 (HIGH) # Step 2: Identify refactoring opportunities # - Extract validation logic into separate functions (lines 45-80) # - Replace nested if statements with early returns (lines 90-120) # - Extract complex condition into named function (line 105) # Step 3: Apply refactorings using Edit tool # [Use Edit tool to implement changes] # Step 4: Verify improvement pmat analyze complexity --path src/services/validator.rs # Expected output: # Function: validate_request (refactored) # Cyclomatic Complexity: 6 (GOOD) ← Reduced from 18 # Cognitive Complexity: 8 (GOOD) ← Reduced from 24 # Lines: 80 ← Reduced from 150 # Nesting Depth: 2 (GOOD) ← Reduced from 4 # Improvement: 67% reduction in cyclomatic complexity ``` ### Example 2: Dead Code Cleanup ```bash # Step 1: Identify dead code pmat analyze dead-code --path src/ # Output: # Found 15 unused functions: # 1. src/utils/formatter.rs::legacy_format() - Last used in v1.2 # 2. src/helpers/validation.rs::old_validator() - Replaced by new_validator() # 3. src/api/deprecated.rs::old_endpoint() - Deprecated in v2.0 # ... # Step 2: Review and confirm removal safety # Check git history, grep for usage, review tests # Step 3: Remove dead code using Edit tool # [Remove each unused function] # Step 4: Measure impact # - Binary size reduced by ~45KB # - Maintainability index improved from 62 to 75 # - Reduced cognitive load for developers ``` ### Example 3: Extract Method Refactoring ```bash # Step 1: Identify extraction candidate pmat analyze complexity --path src/core/processor.rs --format detailed # Output: # Function: process_data # Lines 100-180: Complexity 12 (candidate for extraction) # Lines 200-250: Complexity 8 (candidate for extraction) # Step 2: Extract complex sections into named methods # Before: # fn process_data(input: &str) -> Result { # // Lines 100-180: Data validation (complexity 12) # // Lines 200-250: Data transformation (complexity 8) # } # After (using Edit tool): # fn process_data(input: &str) -> Result { # let validated = validate_input_data(input)?; # transform_validated_data(validated) # } # # fn validate_input_data(input: &str) -> Result { # // Extracted validation logic # } # # fn transform_validated_data(data: Data) -> Result { # // Extracted transformation logic # } # Step 3: Verify improvement pmat analyze complexity --path src/core/processor.rs # Results: # - process_data: Complexity 3 (SIMPLE) ← Reduced from 20 # - validate_input_data: Complexity 6 (MODERATE) # - transform_validated_data: Complexity 4 (SIMPLE) # Total complexity: 13 (distributed across 3 testable functions) ``` ## Refactoring Decision Matrix Use this matrix to prioritize refactoring efforts: | Complexity | Churn (changes/month) | Priority | Action | |------------|----------------------|----------|--------| | High (>15) | High (>10) | CRITICAL | Refactor immediately | | High (>15) | Low (<3) | HIGH | Refactor when modifying | | Medium (8-15) | High (>10) | HIGH | Simplify hot paths | | Medium (8-15) | Low (<3) | MEDIUM | Monitor, refactor if needed | | Low (<8) | Any | LOW | No action needed | **Generate this matrix using**: ```bash # Combine complexity + churn analysis pmat analyze complexity --path src/ --output complexity.json pmat analyze churn --path src/ --since "6 months ago" --output churn.json pmat refactor-matrix --complexity complexity.json --churn churn.json ``` ## Refactoring Safety Checklist Before applying refactorings: 1. ✅ **Baseline metrics captured** (complexity, quality, test coverage) 2. ✅ **Tests exist and pass** (run `pmat test` or project test suite) 3. ✅ **Git commit created** (safe rollback point) 4. ✅ **Refactoring scope defined** (one pattern at a time) 5. ✅ **Impact understood** (dependencies, callers identified) After applying refactorings: 1. ✅ **Tests still pass** (regression check) 2. ✅ **Complexity reduced** (verify with `pmat analyze complexity`) 3. ✅ **Functionality preserved** (manual smoke test) 4. ✅ **Code review requested** (peer validation) ## Integration with PMAT Quality Analysis Refactoring should be guided by quality metrics: ```bash # Generate comprehensive quality report pmat analyze quality --path src/ --output quality_report.json # Identify refactoring targets from quality report # - Functions with maintainability index < 50 # - Files with technical debt > 10 hours # - Modules with high coupling scores # Apply targeted refactorings # [Use patterns above] # Verify quality improvement pmat analyze quality --path src/ --output quality_after.json pmat compare-quality --before quality_report.json --after quality_after.json ``` ## Scientific Foundation PMAT refactoring implements peer-reviewed principles: 1. **Fowler's Refactoring Catalog** (1999) - Extract Method, Simplify Conditional, Remove Dead Code - Behavior-preserving transformations 2. **McCabe's Cyclomatic Complexity** (1976) - Threshold: 10 for well-structured code - Predictor of defect density 3. **Cognitive Complexity** (SonarSource, 2021) - Measures mental effort required to understand code - Guide for simplification priorities 4. **Technical Debt Quadrant** (Fowler, 2009) - Distinguish deliberate vs. inadvertent debt - Prioritize repayment strategies ## Performance Optimization Tips For large codebases: 1. **Incremental Refactoring**: Refactor one file/function at a time 2. **Hot Path Priority**: Focus on frequently changed files first 3. **Complexity Threshold**: Only refactor complexity > 10 (Pareto principle) 4. **Measure Impact**: Track time saved via maintainability improvements ## Common Refactoring Patterns by Language ### Rust - Replace `unwrap()` with proper error handling (`?` operator) - Extract complex `match` arms into functions - Use `impl Trait` to simplify return types - Apply lifetime elision rules ### Python - Extract nested functions for clarity - Replace complex comprehensions with explicit loops - Use `dataclasses` for data structures - Apply type hints for better IDE support ### JavaScript/TypeScript - Extract arrow function logic into named functions - Replace callback hell with `async/await` - Use destructuring to simplify parameter passing - Apply optional chaining (`?.`) to reduce null checks ### Go - Extract error handling into helper functions - Simplify interface implementations - Use `defer` for cleanup logic - Apply table-driven tests ## When NOT to Refactor Avoid refactoring in these scenarios: 1. **No Tests**: Without tests, refactoring is unsafe (write tests first) 2. **Unclear Requirements**: Understand the domain before changing code 3. **Hot Production Issues**: Fix bugs first, refactor later 4. **Large-Scale Changes**: Break into smaller, incremental refactorings 5. **Working Code**: If complexity is low and code is stable, leave it ## Limitations - **Semantic Preservation**: PMAT suggests refactorings but cannot guarantee behavior preservation (test coverage required) - **Context Awareness**: Automated suggestions may not account for domain-specific constraints - **Language-Specific Idioms**: Some refactorings require language-specific expertise - **External Dependencies**: Refactoring may require updating API contracts ## Error Handling If refactoring causes issues: 1. **Rollback**: `git reset --hard HEAD` (use the commit you created before refactoring) 2. **Incremental Revert**: Use Edit tool to undo specific changes 3. **Test Isolation**: Identify which refactoring broke tests 4. **Consult Baseline**: Compare against baseline metrics to identify regressions ## Best Practices 1. **One Pattern at a Time**: Apply one refactoring pattern per commit 2. **Test After Each Change**: Verify tests pass after each refactoring 3. **Commit Frequently**: Create rollback points for safety 4. **Measure Impact**: Track complexity reduction and quality improvement 5. **Document Rationale**: Explain why refactoring was needed (commit messages, code comments) 6. **Peer Review**: Get feedback on refactoring approach before merging ## Integration with Other PMAT Skills **Workflow Recommendation**: 1. **pmat-context**: Understand codebase structure 2. **pmat-quality**: Identify quality issues 3. **pmat-refactor**: Apply systematic improvements ← This skill 4. **pmat-tech-debt**: Track debt repayment progress ## Version Requirements - **Minimum**: PMAT v2.170.0 - **Recommended**: Latest version for best refactoring suggestions - **Check version**: `pmat --version` --- **Remember**: Refactoring is about improving code structure WITHOUT changing behavior. Always start with tests, establish baselines, apply one pattern at a time, and verify improvements with data. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/paiml) — claim your Tome and manage your conversions.