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

Analysis Dimensions

duplication-analysis

algorithm-efficiency

clean-code-checks

architectural-fit

clean-code-checks

clean-code-checks

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

• [E1]

  ,

  [E2]

  references for each finding
• Metrics before/after where measurable
• Principle violations cited

Fallback: If

imbue

[E1]

Tiered Analysis

Cross-Plugin Dependencies

pensive:shared

imbue:evidence-logging

conserve:code-quality-principles

archetypes:architecture-paradigms

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