Refine Code

Analyze living code for quality issues and generate a prioritized refactoring plan.

When To Use

Use this command when you need to:

• After AI-assisted development to check for slop
• Before releases as a quality gate
• When code works but needs improvement
• Systematic refactoring of living code
• Reducing duplication and algorithmic inefficiency

When NOT To Use

Avoid this command if:

• Removing dead/unused code (use /unbloat)
• Bug hunting (use /bug-review)
• Selecting architecture paradigm (use archetypes)

Philosophy

• Craft over speed: Counter AI velocity with intentional quality
• Living code focus: Improve code that stays, not remove code that's dead
• Evidence-based: Every finding has file:line references and principle citations
• Actionable: Concrete before/after proposals, not vague suggestions

Usage

# Quick quality scan (Tier 1, default)
/refine-code

# Scan specific path
/refine-code src/

# Targeted analysis (Tier 2)
/refine-code --level 2
/refine-code --level 2 --focus duplication
/refine-code --level 2 --focus algorithms

# Deep analysis (Tier 3)
/refine-code --level 3 --report quality-report.md

# Apply refinements interactively
/refine-code --apply

Options

Analysis Dimensions

Scan Tiers

Tier 1: Quick (2-5 min)

• Complexity hotspots (long methods, god classes)
• Obvious duplication (exact blocks)
• Naming issues (generic names)
• Magic numbers
• Bare excepts

Tier 2: Targeted (10-20 min)

• Full duplication scan with structural similarity
• Algorithm inefficiency patterns
• Architectural coupling checks
• Anti-slop pattern detection
• Error handling completeness

Tier 3: Deep (30-60 min)

• All Tier 1 and Tier 2
• Cross-module dependency analysis
• Paradigm fitness evaluation (if archetypes available)
• Thorough refactoring plan with before/after code
• Quality score with benchmarks

Example Session

$ /refine-code src/ --level 2

Phase 1: Context
  Language: Python | Framework: FastAPI | Size: 2,847 lines (34 files)

Phase 2: Scanning (6 dimensions)
  [################] 34 files analyzed (8.3s)

Phase 3: Findings

[1/14] DUPLICATION | HIGH | SMALL effort
  src/handlers/user.py:45-62 <-> src/handlers/order.py:23-40
  18 duplicate lines (entity permission validation)
  Strategy: Extract to shared validate_permissions()

[2/14] ALGORITHM | HIGH | SMALL effort
  src/matching.py:45-58
  Nested loop on same collection: O(n^2)
…

Interactive Apply Mode

When --apply is used:

1. Creates backup branch: backup/refine-YYYYMMDD-HHMMSS
2. Shows each finding with proposed change
3. Prompts: [y]es / [n]o / [d]iff / [s]kip rest / [q]uit
4. Runs tests after each change
5. Rolls back on test failure
6. Reports summary with rollback instructions

Plugin Dependencies

Relationship to Other Commands

See Also

• code-refinement skill: Analysis dimensions and detection patterns
• code-refiner agent: Orchestration implementation
• /cleanup command: Unified cleanup orchestrator (conserve, if available)
• conserve:code-quality-principles: KISS/YAGNI/SOLID reference (if available)
• archetypes:architecture-paradigms: Paradigm detection (if available)