Table of Contents
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
| # |
Dimension |
Module |
What It Catches |
| 1 |
Duplication & Redundancy |
duplication-analysis |
Near-identical blocks, similar functions, copy-paste |
| 2 |
Algorithmic Efficiency |
algorithm-efficiency |
O(n^2) where O(n) works, unnecessary iterations |
| 3 |
Clean Code Violations |
clean-code-checks |
Long methods, deep nesting, poor naming, magic values |
| 4 |
Architectural Fit |
architectural-fit |
Paradigm mismatches, coupling violations, leaky abstractions |
| 5 |
Anti-Slop Patterns |
clean-code-checks |
Premature abstraction, enterprise cosplay, hollow patterns |
| 6 |
Error Handling |
clean-code-checks |
Bare excepts, swallowed errors, happy-path-only |
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
refine:context-established — Scope, language, framework detection
refine:scan-complete — Findings across all dimensions
refine:prioritized — Findings ranked by impact and effort
refine:plan-generated — Concrete refactoring plan with before/after
refine:evidence-captured — Evidence appendix per imbue:proof-of-work
Workflow
Step 1: Establish Context (refine:context-established)
Detect project characteristics:
# Language detection
find . -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
-not -path "*/node_modules/*" -not -path "*/.git/*" \
\( -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 . -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
-not -path "*/node_modules/*" -not -path "*/.git/*" \
\( -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:proof-of-work (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
| Tier |
Time |
Scope |
| 1: Quick (default) |
2-5 min |
Complexity hotspots, obvious duplication, naming, magic values |
| 2: Targeted |
10-20 min |
Algorithm analysis, full duplication scan, architectural alignment |
| 3: Deep |
30-60 min |
All above + cross-module coupling, paradigm fitness, comprehensive plan |
Cross-Plugin Dependencies
| Dependency |
Required? |
Fallback |
pensive:shared |
Yes |
Core review patterns |
imbue:proof-of-work |
Optional |
Inline evidence in report |
conserve:code-quality-principles |
Optional |
Built-in KISS/YAGNI/SOLID checks |
archetypes:architecture-paradigms |
Optional |
Principle-based checks only (no paradigm detection) |
Supporting Modules
- Code quality analysis - duplication detection commands and consolidation strategies
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
1---2name: code-refinement3description: 'Analyze and improve living code quality: duplication, algorithmic efficiency,4 clean code principles, architectural fit, anti-slop patterns, and error handling5 robustness. Use when improving code quality, reducing AI slop, refactoring for clarity,6 optimizing algorithms, applying clean code principles. Do not use when removing7 dead/unused code (use conserve:bloat-detector). reviewing for bugs (use pensive:bug-review).8 selecting architecture paradigms (use archetypes skills). This skill actively improves9 living code, complementing bloat detection (dead code removal) with quality refinement10 (living code improvement).'11category: code-quality12tags:13- refactoring14- clean-code15- algorithms16- duplication17- anti-slop18- craft19tools:20- Read21- Grep22- Glob23- Bash24usage_patterns:25- code-quality-improvement26- duplication-reduction27- algorithm-optimization28- clean-code-enforcement29complexity: advanced30estimated_tokens: 35031progressive_loading: true32dependencies:33- pensive:shared34- pensive:safety-critical-patterns35- imbue:proof-of-work36modules:37- modules/duplication-analysis.md38- modules/algorithm-efficiency.md39- modules/clean-code-checks.md40- modules/architectural-fit.md41metadata:42 source: https://skillmd.com/skills/micsapp/code-refinement43---4445## Table of Contents4647- [Quick Start](#quick-start)48- [When to Use](#when-to-use)49- [Analysis Dimensions](#analysis-dimensions)50- [Progressive Loading](#progressive-loading)51- [Required TodoWrite Items](#required-todowrite-items)52- [Workflow](#workflow)53- [Tiered Analysis](#tiered-analysis)54- [Cross-Plugin Dependencies](#cross-plugin-dependencies)5556# Code Refinement Workflow5758Analyze and improve living code quality across six dimensions.5960## Quick Start6162```bash63/refine-code64/refine-code --level 2 --focus duplication65/refine-code --level 3 --report refinement-plan.md66```6768## When To Use6970- After rapid AI-assisted development sprints71- Before major releases (quality gate)72- When code "works but smells"73- Refactoring existing modules for clarity74- Reducing technical debt in living code7576## When NOT To Use7778- Removing79 dead/unused code (use conserve:bloat-detector)80- Removing81 dead/unused code (use conserve:bloat-detector)8283## Analysis Dimensions8485| # | Dimension | Module | What It Catches |86|---|-----------|--------|----------------|87| 1 | Duplication & Redundancy | `duplication-analysis` | Near-identical blocks, similar functions, copy-paste |88| 2 | Algorithmic Efficiency | `algorithm-efficiency` | O(n^2) where O(n) works, unnecessary iterations |89| 3 | Clean Code Violations | `clean-code-checks` | Long methods, deep nesting, poor naming, magic values |90| 4 | Architectural Fit | `architectural-fit` | Paradigm mismatches, coupling violations, leaky abstractions |91| 5 | Anti-Slop Patterns | `clean-code-checks` | Premature abstraction, enterprise cosplay, hollow patterns |92| 6 | Error Handling | `clean-code-checks` | Bare excepts, swallowed errors, happy-path-only |9394## Progressive Loading9596Load modules based on refinement focus:9798- **`modules/duplication-analysis.md`** (~400 tokens): Duplication detection and consolidation99- **`modules/algorithm-efficiency.md`** (~400 tokens): Complexity analysis and optimization100- **`modules/clean-code-checks.md`** (~450 tokens): Clean code, anti-slop, error handling101- **`modules/architectural-fit.md`** (~400 tokens): Paradigm alignment and coupling102103Load all for comprehensive refinement. For focused work, load only relevant modules.104105## Required TodoWrite Items1061071. `refine:context-established` — Scope, language, framework detection1082. `refine:scan-complete` — Findings across all dimensions1093. `refine:prioritized` — Findings ranked by impact and effort1104. `refine:plan-generated` — Concrete refactoring plan with before/after1115. `refine:evidence-captured` — Evidence appendix per `imbue:proof-of-work`112113## Workflow114115### Step 1: Establish Context (`refine:context-established`)116117Detect project characteristics:118```bash119# Language detection120find . -not -path "*/.venv/*" -not -path "*/__pycache__/*" \121 -not -path "*/node_modules/*" -not -path "*/.git/*" \122 \( -name "*.py" -o -name "*.ts" -o -name "*.rs" -o -name "*.go" \) \123 | head -20124125# Framework detection126ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null127128# Size assessment129find . -not -path "*/.venv/*" -not -path "*/__pycache__/*" \130 -not -path "*/node_modules/*" -not -path "*/.git/*" \131 \( -name "*.py" -o -name "*.ts" -o -name "*.rs" \) \132 | xargs wc -l 2>/dev/null | tail -1133```134135### Step 2: Dimensional Scan (`refine:scan-complete`)136137Load relevant modules and execute analysis per tier level.138139### Step 3: Prioritize (`refine:prioritized`)140141Rank findings by:142- **Impact**: How much quality improves (HIGH/MEDIUM/LOW)143- **Effort**: Lines changed, files touched (SMALL/MEDIUM/LARGE)144- **Risk**: Likelihood of introducing bugs (LOW/MEDIUM/HIGH)145146Priority = HIGH impact + SMALL effort + LOW risk first.147148### Step 4: Generate Plan (`refine:plan-generated`)149150For each finding, produce:151- File path and line range152- Current code snippet153- Proposed improvement154- Rationale (which principle/dimension)155- Estimated effort156157### Step 5: Evidence Capture (`refine:evidence-captured`)158159Document with `imbue:proof-of-work` (if available):160- `[E1]`, `[E2]` references for each finding161- Metrics before/after where measurable162- Principle violations cited163164**Fallback**: If `imbue` is not installed, capture evidence inline in the report using the same `[E1]` reference format without TodoWrite integration.165166## Tiered Analysis167168| Tier | Time | Scope |169|------|------|-------|170| **1: Quick** (default) | 2-5 min | Complexity hotspots, obvious duplication, naming, magic values |171| **2: Targeted** | 10-20 min | Algorithm analysis, full duplication scan, architectural alignment |172| **3: Deep** | 30-60 min | All above + cross-module coupling, paradigm fitness, comprehensive plan |173174## Cross-Plugin Dependencies175176| Dependency | Required? | Fallback |177|------------|-----------|----------|178| `pensive:shared` | Yes | Core review patterns |179| `imbue:proof-of-work` | Optional | Inline evidence in report |180| `conserve:code-quality-principles` | Optional | Built-in KISS/YAGNI/SOLID checks |181| `archetypes:architecture-paradigms` | Optional | Principle-based checks only (no paradigm detection) |182183## Supporting Modules184185- [Code quality analysis](modules/code-quality-analysis.md) - duplication detection commands and consolidation strategies186187When optional plugins are not installed, the skill degrades gracefully:188- Without `imbue`: Evidence captured inline, no TodoWrite proof-of-work189- Without `conserve`: Uses built-in clean code checks (subset)190- Without `archetypes`: Skips paradigm-specific alignment, uses coupling/cohesion principles only