Code Improvement & Cleanup Skill

Systematic improvements with multi-persona expertise and safety validation.

Quick Start

# Quality improvement
/sc:improve src/ --type quality --safe

# Performance optimization
/sc:improve api-endpoints --type performance

# Dead code cleanup
/sc:improve src/ --cleanup --type code --safe

# Import optimization
/sc:improve --cleanup --type imports

Behavioral Flow

1. Analyze - Examine codebase for improvement opportunities
2. Plan - Choose approach and activate relevant personas
3. Execute - Apply systematic improvements
4. Validate - Ensure functionality preservation
5. Document - Generate improvement summary

Flags

Flag	Type	Default	Description
--type	string	quality	quality, performance, maintainability, style, principles, code, imports, files, all
--cleanup	bool	false	Enable cleanup mode
--safe	bool	true	Conservative with safety validation
--aggressive	bool	false	Thorough cleanup (use with caution)
--preview	bool	false	Show changes without applying
--interactive	bool	false	Guided decision mode

Personas Activated

• architect - Structure and design improvements
• performance - Optimization expertise
• quality - Code quality and maintainability
• security - Security pattern application
• code-warden - KISS and Purity enforcement (with --type principles)

MCP Integration

PAL MCP (Validation & Analysis)

Tool	When to Use	Purpose
mcp__pal__consensus	Complex refactors	Multi-model validation before major changes
mcp__pal__codereview	Quality assessment	Review improvement quality and safety
mcp__pal__thinkdeep	Architecture changes	Deep analysis of structural improvements
mcp__pal__precommit	Before commit	Validate all changes preserve functionality
mcp__pal__debug	Regression issues	Root cause analysis if improvements break things
mcp__pal__challenge	Aggressive mode	Critical evaluation of aggressive cleanup decisions

PAL Usage Patterns

# Consensus for major refactor
mcp__pal__consensus(
    models=[
        {"model": "gpt-5.2", "stance": "for"},
        {"model": "gemini-3-pro", "stance": "against"}
    ],
    step="Evaluate: Should we extract this into a separate module?"
)

# Review after improvements
mcp__pal__codereview(
    review_type="full",
    step="Reviewing code improvements",
    findings="Quality, maintainability, backwards compatibility",
    relevant_files=["/src/refactored/module.py"]
)

# Pre-commit validation
mcp__pal__precommit(
    path="/path/to/repo",
    step="Validating refactoring changes",
    confidence="high"
)

Rube MCP (Automation & Tracking)

Tool	When to Use	Purpose
mcp__rube__RUBE_SEARCH_TOOLS	External tools	Find linters, formatters, analyzers
mcp__rube__RUBE_MULTI_EXECUTE_TOOL	Notifications	Update tickets, notify team
mcp__rube__RUBE_CREATE_UPDATE_RECIPE	Reusable workflows	Save improvement patterns

Rube Usage Patterns

# Notify team of improvements
mcp__rube__RUBE_MULTI_EXECUTE_TOOL(tools=[
    {"tool_slug": "SLACK_SEND_MESSAGE", "arguments": {
        "channel": "#refactoring",
        "text": "Completed: Dead code cleanup removed 500 lines"
    }},
    {"tool_slug": "JIRA_UPDATE_ISSUE", "arguments": {
        "issue_key": "TECH-456",
        "status": "Done"
    }}
])

# Create improvement report in Notion
mcp__rube__RUBE_MULTI_EXECUTE_TOOL(tools=[
    {"tool_slug": "NOTION_CREATE_PAGE", "arguments": {
        "title": "Refactoring Report - Q4 2025",
        "content": "## Summary\n- Lines removed: 500\n- Complexity reduced: 25%"
    }}
])

Evidence Requirements

This skill requires evidence. You MUST:

• Show before/after code comparisons
• Run tests to verify functionality preservation
• Report metrics (lines removed, complexity reduction)

Improvement Types

Quality (--type quality)

• Technical debt reduction
• Code structure improvements
• Readability enhancements

Performance (--type performance)

• Bottleneck resolution
• Algorithm optimization
• Resource efficiency

Maintainability (--type maintainability)

• Complexity reduction
• Documentation improvements
• Modular restructuring

Style (--type style)

• Formatting consistency
• Naming conventions
• Pattern alignment

Principles (--type principles)

• KISS compliance improvements (reduce complexity, extract methods)
• Purity enforcement (separate I/O from logic)
• Guard clause refactoring (reduce nesting)
• Functional core extraction (move I/O to shell layer)

Validators:

# Run KISS validation
python .claude/skills/sc-principles/scripts/validate_kiss.py --scope-root . --json

# Run Purity validation
python .claude/skills/sc-principles/scripts/validate_purity.py --scope-root . --json

Cleanup Mode (--cleanup)

Code Cleanup (--type code)

• Dead code detection and removal
• Unused variable elimination
• Unreachable code removal

Import Cleanup (--type imports)

• Unused import removal
• Import organization
• Dependency optimization

File Cleanup (--type files)

• Empty file removal
• Orphaned file detection
• Structure optimization

Full Cleanup (--type all)

• Comprehensive cleanup
• All categories combined
• Multi-persona coordination

Safety Modes

Safe Mode (--safe)

• Conservative changes only
• Automatic safety validation
• Preserves all functionality

Aggressive Mode (--aggressive)

• Thorough cleanup
• Framework-aware patterns
• Requires careful review

Examples

Safe Quality Improvement

/sc:improve src/ --type quality --safe
# Technical debt reduction with safety validation

Performance Optimization

/sc:improve api-endpoints --type performance --interactive
# Guided optimization with profiling analysis

Dead Code Cleanup

/sc:improve src/ --cleanup --type code --safe
# Remove unused code with dependency validation

Preview Changes

/sc:improve --cleanup --type imports --preview
# Show what would be removed without executing

Tool Coordination

• Read/Grep/Glob - Code analysis
• Edit/MultiEdit - Safe modifications
• TodoWrite - Progress tracking
• Task - Large-scale improvement delegation