Table of Contents

• •Quick Start
• •When to Use
• •Analysis Dimensions
• •Progressive Loading
• •Required TodoWrite Items
• •Workflow
• •Tiered Analysis
• •Cross-Plugin Dependencies

Code Refinement Workflow

Analyze and improve living code quality across six dimensions.

Quick Start

/refine-code
/refine-code --level 2 --focus duplication
/refine-code --level 3 --report refinement-plan.md

When To Use

• •After rapid AI-assisted development sprints
• •Before major releases (quality gate)
• •When code "works but smells"
• •Refactoring existing modules for clarity
• •Reducing technical debt in living code

When NOT To Use

• •Removing dead/unused code (use conserve:bloat-detector)
• •Removing dead/unused code (use conserve:bloat-detector)

Analysis Dimensions

Progressive Loading

Load modules based on refinement focus:

• •modules/duplication-analysis.md (~400 tokens): Duplication detection and consolidation
• •modules/algorithm-efficiency.md (~400 tokens): Complexity analysis and optimization
• •modules/clean-code-checks.md (~450 tokens): Clean code, anti-slop, error handling
• •modules/architectural-fit.md (~400 tokens): Paradigm alignment and coupling

Load all for comprehensive refinement. For focused work, load only relevant modules.

Required TodoWrite Items

1. •refine:context-established — Scope, language, framework detection
2. •refine:scan-complete — Findings across all dimensions
3. •refine:prioritized — Findings ranked by impact and effort
4. •refine:plan-generated — Concrete refactoring plan with before/after
5. •refine:evidence-captured — Evidence appendix per imbue:evidence-logging

Workflow

Step 1: Establish Context (refine:context-established)

Detect project characteristics:

# Language detection
find . -name "*.py" -o -name "*.ts" -o -name "*.rs" -o -name "*.go" | head -20

# Framework detection
ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null

# Size assessment
find . -name "*.py" -o -name "*.ts" -o -name "*.rs" | xargs wc -l 2>/dev/null | tail -1

Step 2: Dimensional Scan (refine:scan-complete)

Load relevant modules and execute analysis per tier level.

Step 3: Prioritize (refine:prioritized)

Rank findings by:

• •Impact: How much quality improves (HIGH/MEDIUM/LOW)
• •Effort: Lines changed, files touched (SMALL/MEDIUM/LARGE)
• •Risk: Likelihood of introducing bugs (LOW/MEDIUM/HIGH)

Priority = HIGH impact + SMALL effort + LOW risk first.

Step 4: Generate Plan (refine:plan-generated)

For each finding, produce:

• •File path and line range
• •Current code snippet
• •Proposed improvement
• •Rationale (which principle/dimension)
• •Estimated effort

Step 5: Evidence Capture (refine:evidence-captured)

Document with imbue:evidence-logging (if available):

• •[E1], [E2] references for each finding
• •Metrics before/after where measurable
• •Principle violations cited

Fallback: If imbue is not installed, capture evidence inline in the report using the same [E1] reference format without TodoWrite integration.

Tiered Analysis

Cross-Plugin Dependencies

When optional plugins are not installed, the skill degrades gracefully:

• •Without imbue: Evidence captured inline, no TodoWrite proof-of-work
• •Without conserve: Uses built-in clean code checks (subset)
• •Without archetypes: Skips paradigm-specific alignment, uses coupling/cohesion principles only